RSX-11M 


Guide to Writing 
an 1/0 Driver 
Order No. DEC-11-OMWDA-B-D 


RSX-11M 


Guide to Writing 
an 1/0 Driver 
Order No. DEC-11-OMWDA-B-D 


RSX-1LIM Version 2 


digital equipment corporation - maynard. massachusetts 


First Printing, April 1975 
Revised, September 1975 


The information in this document is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporation. Digital Equipment Corporation assumes no responsibility 
for any errors that may appear in this document. 


The software described in this document is furnished under a license 
and may only be used or copied in accordance to the terms of such 
license. 


Digital Equipment Corporation assumes no responsibility for the use 
or reliability of its software on equipment that is not supplied by 
Digital. 


Copyright () 1975 by Digital Equipment Corporation 


The postage prepaid READER'S COMMENTS form on the last page of this 
document requests the user's critical evaluation to assist us in 
preparing future documentation. 


The following are trademarks of Digital Equipment Corporation: 


DIGITAL DECsystem-10 MASSBUS 
DEC DECtape OMNIBUS 
PDP DIBOL OS/8 

DECUS EDUSYSTEM PHA 

UNIBUS FLIP: CHIP RSTS 
COMPUTER LABS FOCAL RSX 

COMTEX INDAC TYPESET-8 
DDT LAB-8 TYPESET-11 
DECCOMM 


LIMITED RIGHTS LEGEND 


Contract No. 
Contractor or Subcontractor: Digital Equipment Corporation 


All the material contained herein is considered limited rights data 
under such contract. 


1/76-15 


PREFACE 


CHAPTER 


WN ke 


OOo 


kK 


eo @ @ © © eo @« @ © «@ 
NNN NN 


e e e e e 
OMNIA P he PSE BW WW WWWWWWNDNYDNDNDYD PO 


BPR RPP RP EPP RP PREP RP RP BPP EP RP EPP RP EP RP RP RP RPP RP EP EP RPP eRe 


bh 
On 


Spe 


NONNNMNN WY 
NOS WN FE 


“OO BWW DN Fb 
= 


NONNNNE 
° e e 


&m WD F 


e e 
WWNrF 
-_ 


e 
WwW 
iw) 


e 
& W 


CONTENTS 


MANUAL OBJECTIVES AND READER ASSUMPTIONS 
STRUCTURE OF THE DOCUMENT 


an QOATAMMIMN MRAMTIMAGATMES 
ASSOCIATED DOCUMENTS 


THE RSX-11M I/O SYSTEM - PHILOSOPHY AND 
STRUCTURE 


I/O PHILOSOPHY 
STRUCTURE 

I/O Hierarchy 
FCS 


Device Interrupt 

I/O Initiator 

Device Timeout 

Cancel I/O 

Power Failure 

Summary 

DATA STRUCTURES 

The Device Control Block (DCB) 

The Unit Control Block (UCB) 

The Status Control Block (SCB) 
Interrelation of the I/O Control Blocks 
The 1/0 Packet 

The I/O Queue 

The Fork List 

The Device Interrupt Vector 

EXECUTIVE SERVICES 

Pre-Driver Initiation Processing 
Post-Driver Initiation Services 
Interrupt Save (SINTSV) 

Get Packet (S$GTPKT) 

Create Fork Process (S$FORK) 

I/O Done (S$IODON) 

PROGRAMMING STANDARDS 

Process-Like Characteristics of a Driver 
Programming Conventions 

Programming Protocol 

Processing at Priority 7 with Interrupts 
Locked Out 


Processing at the Priority of the Interrupting 


Source 

Processing at Fork Level 
Programming Protocol Summary 
FLOW OF AN I/O REQUEST 


DATA STRUCTURES AND THEIR INTERRELATIONSHIPS 


Data Structures Summary 


hints 


{ § tt do bob te t t 4 


PREP PRP RPP RPE PRP RPP RPP RP EPP RPP 2 
i 
FPFOWDOADMUDADUUNFEEREABERWWNEEE 


CHAPTER 


CHAPTER 


CHAPTER 


CHAPTER 


2 


NO Nd 


Ww 


> 


NNNNNNNNN ND ND LN 


WWW WWW WWW WwW NB NMNM NN NNN NB NH WH HD HO 


ui olin 


& WD Fe 


WNRE EEE 


e 
Sf PWWWWWWWWwDn+- 


H 


ee 8 ¢@ 

e 

e 

Um WN 


a 
a 
a 


e 
WWWWWWN RRR Re 


e 
On & WN 


a 
UP Ph K Hh LH Ph hh LH 
e 


mn on 
ee e¢ 
NF 


NF 


oo 


PREP RPP RPP PEE 
BPWWNNNH HE 


om 


e 
e 


CONTENTS (Cont. ) 


INCORPORATING USER-WRITTEN DRIVERS INTO 
RSX-11M 


INTRODUCTION 

OVERVIEW 

INCORPORATING A DRIVER - DETAILS 

Creating the Data Structure 

Required Device Control Block (DCB) Fields 
Required Unit Control Block (UCB) Fields 
Required Status Control Block (SCB) Fields 
Source Format of the Data Structure 
Creating the Driver Source Code 
Incorporating the User-Written Driver 
DRIVER DEBUGGING 

Rebuilding and Re-incorporating the User 
Driver 

Re-Assembly 

Updating the Executive Object Module Library 
Rebuilding the Executive 

Incorporating Tasks into the System 
Bootstrapping the New System 

RSX-11M Executive Debugging Tool 

Fault Isolation - Some General Hints 
Introduction 

Fault Classifications 

Immediate Servicing 

Other Pertinent Fault Isolation Data 

Fault Tracing 

SAMPLE OUTPUT FROM CRASH AND PANIC DUMP 
ROUTINES 

Crash Output 

Panic Dump Output 


WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS 


DATA STRUCTURES 

The I/O Packet 

I/O Packet Details 

The Device Control Block (DCB) 
DCB Details 

I/O Function Codes 

The Status Control Block (SCB) 
SCB Details 

The Unit Control Block (UCB) 
UCB Details 


EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 


SYSTEM-STATE REGISTER CONVENTIONS 
SERVICE CALLS 


INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE 
DEVICE DESCRIPTION 

DATA STRUCTURE AND DRIVER SOURCE 

The Data Structure 

Driver Code 


iv 


Page 


t 
aa 


MNMNNONNNNNNDND 29 
I 
NUP BP WNMNNH EH 


1 ot ! 
rPrRrwOoOOmOOO~)~) ~I 


NN NN DN NN ND NH flo 
| 


APPENDIX 


APPENDIX 


INDEX 


Figure 


Table 


pp oD 
bk 


WWWWWNHNNNNEKEEH 
I 
UO BWM EUR WNP BW Nb 


3=L 


CONTENTS (Cont.) 


DEVELOPMENT OF THE ADDRESS DOUBLEWORD 


INTRODUCTION 
CREATING THE ADDRESS DOUBLEWORD 


SYSTEM DATA STRUCTURES AND SYMBOLIC 
DEFINITIONS 


I/O Control Flow 

DL11 Disk I/O Data Structure 

RK11 Disk I/O Data Structure 

I/O Data Structure 

Unmapped System Header 

Ma ned System Header 

Stack Structure - Internal SST Fault 
Stack Structure - Non-Normal SST Fault 
Stack Structure - Data Items on Stack 
I/O Packet Format 

QIO Directive Parameter Block (DPB) 
Device Control Block 

Status Control Block 

Unit Control Block 


Standard I/O Function Codes 


Page 


INDEX-1 


ae) 
@ 
Q 
@ 


'ttdod re ee | 
ie) 
Ona UI & CO 


1 
NEFON WER REPRE RPO 


oO OV 


WWWWWNNNNDN NRE FF 
I 


PREFACE 


0.1 MANUAL OBJECTIVES AND READER ASSUMPTIONS 


The goal of this manual is to provide all the information necessary to 
successfully prepare a conventional I/O driver for RSX-11M and 
subsequently incorporate it into an operational user-tailored system. 
A "conventional" driver is best explained by example. Disks and unit 
record devices are considered conventional; the LPS-ll, UDC-1ll, and 
TMl11 are considered non-conventional. Complexity of device servicing 
requirements sets the dividing line, a line not easily established in 
go, no-go terms. 


The manual assumes the reader fully understands the device for which 
he is writing a driver, and has complete familiarity with the PDP-1l 
computer, its peripheral devices, and the software supplied with an 
RSX-11M system. Complete familiarity implies an in-depth exposure to 
the following RSX-11M manuals (See section 0.3 below): 


il. System Generation Manual 

2. 1/0 Drivers Reference Manual 

3. Executive Reference Manual 

4. Utilities Procedures Manual 

5. 1/0 Operations Reference Manual 
Although this manual iS organized tutorially, our reader class 
assumptions reguire a system programmer level of expertise; thus, the 
manual will not contain definitions of data processing terms and 
concepts familiar to senior level professionals. 
As adjuncts to this manual, the reader is advised to study existing 
I/O drivers. The RF-ll disk driver is a good example of an NPR device 
and the TA-1ll (cassette) is illustrative of a programmed I/O device. 
In addition, a perusal of the source code contained in the files 


IOSUB, SYSXT, DRQIO, BFCTL, and DRDSP (stored under UIC [11,10] on the 
source disk) should prove beneficial. 


vil 


0.2 STRUCTURE OF THE DOCUMENT 


This document cascades from chapter to chapter toward increasing 
levels of implementation detail. 


Chapter 1 is a functional description of the RSX-11M device level I/0 
system, covering both data structure and code requirements. 


Chapter 2 details how a user-written driver is incorporated into’ the 
system. 


Together, Chapters 1 and 2 provide a complete understanding of the 
requirements that must be met in creating a system which contains a 
user-written driver. 

Chapter 3 provides programming level details on I/O data structures. 
Chapter 4 covers all the I/O-related Executive services. 

Chapter 5 is an example of a user-written driver. 


Appendix A describes the Address Doubleword. 


Appendix B lists system macros which supply symbolic offsets for 
system data structures. 


0.3 ASSOCIATED DOCUMENTS 


Other manuals closely allied to the purposes of this document are 


described briefly in the RSX-11M/RSX-11S Documentation Directory, 
Order No. DEC~-11-OMUGA-B-D. The Documentation Directory defines the 


intended readership of each manual in the RSX-11M/RSX-11S set and 
provides a brief synopsis of each manual's contents. 
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CHAPTER 1 


THE RSX-11M I/O SYSTEM - PHILOSOPHY AND STRUCTURE 


1.1 I/O PHILOSOPHY 


Memory constraints and RSX-11D compatibility requirements dominated 
the design philosophy and strategy used in creating RSX-11M. To meet 
its performance and space goals, the RSX-l11M I/O system attempts to 
centralize common functions, thus eliminating the inclusion of 
repetitive code in each and every driver in the’ system. To achieve 
this, a substantial effort has been expended in the design of 
RSX-11M's data structures. These structures are used to drive the 
centralized routines; the effect is to substantially reduce the size 
of individual I/O drivers. The table structures, of course, require 
space and must be considered with the total size of the I/O system. 
Nevertheless, the size reduction effected by the centralization of 
functions, combined with table-driven design, has enabled RSX-11M to 
meet its original memory and performance goals. 


In a DEC~released system, DEC-supported drivers are included into’ the 
user-tailored system via system generation queries. User-written 
drivers reguire the user to create object files for I/O data 
structures and driver code. These object files are built and 
incorporated during the generation of the user-tailored system. 


1.2 STRUCTURE 
This section: 


1. Places an I/O driver in the context of the overall RSX-11M 
I/O system; 


2. Establishes the responsibilities of an I/O driver, and 


3. Functionally describes the driver's interface to the 
Executive subroutines and the I/O data structures. 


1.2.1 1/0 Hierarchy 


The RSX-11M I/O system is structured as a loose hierarchy. The term 
"loose" simply indicates that the hierarchy can be entered at any of 
its levels; this characteristic is contrasted to "tight" hierarchies 
which permit entry only from the top. Tight hierarchies exist 
principally for security and protection, but are costly in their 
consumption of equipment resources. Figure 1-1 shows the loose I/0 
system hierarchy. 
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PRIVILEGED NON-PRIVILEGED 


USER 1/0 
REQUEST 


DEVICE 
INDEPENDENT 


DEVICE 
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QIO DIREC QIO DIREC 


USER STATE 


SYSTEM STATE 


QIO DIREC 
SERVICE 


EXEC COMM 
I/O PROC'S 


DEVICE INTERRUPT 1/0 


DRIVER 


Figure 1-1 
I/O Control Flow 


1.2.1.1 FCS - At the top of the hierarchy is File Control Services 
(FCS) which provides device-independent access to devices included in 
a given system configuration. The user task has two levels with which 
to interface with FCS; Get/Put and Read/Write. Get/Put facilitates 
the movement of data records, whereas Read/Write provides a more basic 
level of access affording more direct control over data movement 
between a task and peripheral devices. 


The discussion of FCS has been purposely terse because its existence 
is completely transparent to the driver and rarely concerns the writer 
of a conventional driver. FCS will accept a user request, interpret 
it, and perform all operations necessary to carry out the user 
reguest. 
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1.2.1.2 QI0 - The O10 directive is the lowest level of task I/O. Any 
task may issue a QIO directive. The QIO directive allows more direct 
control over devices which are connected to a system and for which an 
I/O driver exists. The O10 directive forces alli I/O requests from 
user task's to go through the Executive. The Executive prevents tasks 
from destructively interfering with each other and with the Executive. 


1.2.1.3 Executive I/O Processing - The processing of I/O requests. by 


the Executive I/O system is accomplished via: 
l. File Control Primitives (FCP), and 


2. A collection of Executive components consisting of: 


b. I/O-related subroutines, and 
c. The I/O drivers. 


FCP is a privileged task; it is responsible for maintaining the 
structure and integrity of data stored on file-structured volumes. It 
maps virtual block numbers to logical block numbers, extends files, 
and makes volume protection checks. No direct connection exists 
between FCP and a driver. 


Logical blocks are 256 words in length; it is the responsibility of 
the driver to convert a logical block number into a physical address 
on a file-structured device. 


Within the system, FCP exists as a privileged task, possessing all the 
attributes of privileged tasks. FCP requires a partition in which to 
execute. Drivers, on the other hand, are specialized, 
permanently-resident system processes, not tasks. 


The I/O services provided by the Executive consist of QOIO directive 
processing, and a collection of subroutines used by drivers to obtain 
I/O requests, facilitate interrupt handling, and return status upon 
completion of an I/O request (actual control of the device is 
performed by the driver). These subroutines will be examined in 
considerable detail later. Executive Subroutine services and GIO 
directive processing are shown as distinct components but are, in 
fact, both parts of the Executive. These are the routines whicn 
centralize common driver functions, thus eliminating duplicate code 
seguences among drivers. 


The description of the I/O hierarchy and interrelationships is now 
sufficiently complete to allow a more direct consideration of the role 
fulfilled by an I/C driver in an RSX-11M system. 
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1.2.2 Role of I/O Driver in RSX-11M 
Every driver has five entry points: 

1. Device interrupt*; 

2. I/O initiator; 

3. Device timeout; 

4. Cancel I/0, and 

5. Power failure. 


The first entry point is entered via a hardware interrupt; the last 
four are entered by calls from the Executive. These entry points are 
descriptive enough in and of themselves to provide direct insight into 
the responsibilities of a driver; the functional details follow. 


1.2.2.1 Device Interrupt - Control is passed to this entry point when 
a device previously initiated by the driver has completed an I/0 
operation and has caused an interrupt in the central processor. The 
connection to the driver in this instance is direct; the Executive is 
not involved. 


1.2.2.2 I/O Initiator - This entry point is called by the Executive 
to inform the driver that work for it is waiting to be done. In 
effect, this is a wakeup signal for the driver. 


1.2.2.3 Device Timeout - When a driver initiates an I/O operation, it 
establishes a timeout count. If the function does not complete within 
the specified time interval, the Executive will note the time lapse 
and call the driver at this entry point. 


1.2.2.4 Cancel I/O - A number of circumstances arise within the 
system which require that a driver terminate an in-progress I/O 
operation. When this becomes necessary, a task so informs’ the 
Executive which then relays the request to the driver by calling it at 
the cancel I/O entry point. 


1.2.2.5 Power Failure - Two conditions can initiate a call to the 
driver when power is restored following a power failure. First, the 
power failure entry point is automatically called by the Executive any 
time the controller is busy. Secondly, a driver has the option to be 
called regardless of the existence of an outstanding I/O operation at 
the time the power is restored. If power fails, and the conditions 


* A device may trigger more than one distinct interrupt entry. For 
examcle, a full duplex device would have two. 
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exist for power failure code initiation, the Executive will so inform 
the driver by calling it at the power failure entry point when power 
is restored. Frequently, a driver's response to a power failure or an 
T/O failure is identical to that when its device times out: in such a 


case, the power failure entry point may simply be a return, since 
recovery will eventually be effected via the timeout entry point. 


Also, when the system is bootstrapped, a power failure interrupt is 
simulated. This simulation gives drivers the opportunity to carry out 
any pre-operational initialization deemed appropriate. 


1.2.2.6 Summary - Role of an I/O Driver - Functionally, the driver in 
RSX-11M has responsibility for: 


Cc etvemite| IAA TnHeaAwrKiintas 
te servicin Géevice incerrupes; 


2. Initiating I/O operations; 
3. Cancelling in-progress I/O operations, and 


4, Performing device-related functions upon the occurrence of 
timeout or power failure. 


A driver exists as an integral part of the Executive; it can call and 

be called by the Executive. The driver initiates device I/0 

operations directly and receives device interrupts directly. All 
Ss 


other entry points are entered via Executive calls. A driver never 
receives a QIO reguest directly, and has no direct interaction with 
FCP: 


At this point, a functional description of the role of an I/O driver 
in RSX-11M has been presented. In the next three sections, the 


Data structures, 


Programming conventions and protocol 
related to I/O drivers will be discussed. The chapter closes with a 
section discussing the flow of an I/O reguest, from the issuance of a 


QIO directive to the delivery of the requested data to the task. Data 
Structure interrelationships are also covered. 


1.3 DATA STRUCTURES 
There are seven data structures with which an I/O driver interacts: 
l. Device Control Blocks (DCB's); 
2. Unit Control Blocks (UCB'S); 
3. Status Control Blocks (SCB's); 
4. The I/C Packet; 


5. The I/CG Cueue; 
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6. The Fork List, and 
7. Device Interrupt Vectors. 


The first four are most important to the driver, since it is via these 
data structures that all I/O operations are effected. They also serve 
aS communication and coordination vehicles between the Executive and 
individual drivers. 


The I/O Queue and the Fork List are actually Executive data 
structures, but to properly understand the complete interaction of an 
I/O driver with the Executive, their role in the system will also be 
described. The I/O Queue is a list of I/O Packets which are built by 
the QIO directive, principally from information in the caller's 
Directive Parameter Block (DPB). 


Entry to a driver following a device interrupt is direct via_ the 
appropriate hardware device interrupt vector. Since the driver writer 
is responsible for properly establishing this vector, it is included 
in the data structures associated with a driver. 


1.3.1 The Device Control Block (DCB) 


At least one DCB exists for each type of device appearing in a_ system 
(Gevice type should not be equated with a device-unit). The function 
of the DCB is to describe the static characteristics (rather than 
execution-time information) of both the device controller and the 
units attached to the controller. All the DCB's in a system form a 
forward-linked list, with the last CCB having a link of zero. Most of 
the data in the DCB is established in the assembly source for the 
driver data structure. The DCB is used by the CIO directive 
processing code in the Executive and not by the driver. 


1.3.2 The Unit Control Block (UCB) 


One UCB exists for each device-unit attached to a system. Much of the 
information in the UCB is static, though a few dynamic parameters 
exist. For example, the redirect pointer, which reflects the results 
of an MCR Redirect command, is updated dynamically. As with the DCB, 
most of the UCB is established in the assembly source; however, its 
contents are used and modified by both the Executive and the driver, 
though modification of a given datum is done exclusively by either the 
Executive or driver, not both. 


1.3.3 The Status Control Block (SCB) 


One SCB exists for each device controller in the system. This is true 
even if the controller handles more than one device-unit (like the 
RK11 Controller). Line multiplexers such as the DH11 and DJll are 
considered to have a controller per line since all lines may transfer 
in parallel. Most of the information in the SCB is dynamic. The SCB 
is used by both the Executive and the driver. 


THE RSX-11M I/O SYSTEM - PHILOSOPHY AND STRUCTURE 


1.3.3.1 Interrelation of the I/O Control Blocks - Without explicit 
details on the contents of the DCB, UCB, and SCB, their relationships 


are difficult to correlate. This section is intended to represent 


ear P ; ; : 
their interrelationship without entering into the detailed contents of 


the control blocks, leaving such a discussion to be pursued in Chapter 
3. 


Figure 1-2 shows the data structure that would result for three LA30 
DECwriters interfaced via DL11 controllers. The structure requires 
one DCB, three UCB's, and three SCB's, since the activity on all three 
units can proceed in parallel. 


In Figure 1-3, the internal data structure for an RK11 disk controller 
with three units attached is depicted. Note that only one SCB exists 
because only one of the three units may be active at any given time. 


UCB 
SCB SCB 


J fe 
i ae 
had 


Figure 1-2 
DL11 Disk I/O Data Structure 
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DCB 
SCB 
Figure 1-3 


RK11 Disk I/O Data Structure 


Taken together, Figures 1-2 and 1-3 illustrate the strategy underlying 
the existence of three basic I/O control blocks. There need be only 
one DCB per device type. The SCB, depending on the degree of 
parallelism that is desired or possible, can exist for each 
device-unit, or only once for controllers servicing multiple 
device-units. 


As will be seen later, this data structure has the effect of providing 
considerable flexibility in configuring I/G devices, and, due to the 
information density in the structures themselves, substantially 
reduces the code requirements of the associated drivers. 


1.3.4 The I/O Packet 


An I/O Packet contains information extracted from the QIO DPB and 
other information needed to successfully initiate and terminate I/0 
requests. 


1.3.5 The I/O Queue 


Each time an I/O request is made, the Executive is entered, and, if a 
series of validity checks proves successful, the Executive will 
generate a data structure called an I/O Packet. The Executive will 
then insert the packet into a device specific, priority-ordered list 
of packets called the I/O Queue. Each I/O Queue's listhead is located 
in the SCB to which the I/O requests apply. 


When a device driver needs work, it requests the Executive to de-queue 
the next I/O Packet and deliver it to the requesting driver. The 
driver never directly manipulates the I/O Queue. 


THE RSX-11M I/O SYSTEM - PHILOSOPHY AND STRUCTURE 
1.3.6 The Fork List 


All drivers in RSX-11M can easily be written as multi-controller 
drivers; all drivers may run in parallel with other drivers and with 
themselves. When independent processes may execute in parallel, a 
method for synchronizing their access to common data bases is 


essential. At the Executive level in RSX-11M, a_= process may 
synchronize its access to a data base by requesting the Executive to 
transform it into a fork process. Such an operation creates a 


specialized context for the process and places it into a list called 
the Fork List. Processes in the Fork List are granted FIFO access’ to 
common data bases. Once granted access to the data base, the process 
is guaranteed control of the data base until it relinguishes it by 
exiting. Not until the process exits will the next process in the 
Fork List be granted data base access. Thus, it is via the fork 
mechanism and the associated Fork List that access to shared system 
data bases is synchronized. Essentially, of the two basic technigues 
available for data base access synchronization: 


l. Interrupt lockout, and 
2. Access queuing, 


RSX-11M has chosen the latter. 


1.3.7 The Device Interrupt Vector 


The device interrupt vector is initialized when defining data 
Structures, and not dynamically. This makes the driver code 
independent of device register address assignments and the actual 
location of the interrupt vector. 


The driver data structure must include a storage assignment and 
initialization for the interrupt vector with the priority set to 7. 
See lines 81 thru 85 in section 5.2.1 (section 5.2.1 contains the 
source code for the data structure of a sample driver). 


1.4 EXECUTIVE SERVICES 


The I/O-driver-related services provided by the Executive can be 
categorized as pre- and post-driver initiation. The pre-initiation 
services are those performed by the Executive during its processing of 
a CIO directive; these services are not available as Executive calls. 
The goal of this processing is to extract from the driver all I/O 
Support functions not directly related to the actual issuance of a 
function request to a device. If the outcome does not result in the 
cuevueing of an I/O Packet to a driver, the driver is unaware that a 
gIO directive was ever issued. As will be shown shortly, many QIO 
directives do not result in the initiation of an I/O operation. 


i=+9 
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1.4.1 Pre-Driver Initiation Processing 


CIO directive processing performs the following pre-driver initiation 
services: 


1. Checks if the supplied logical unit number (LUN) is legal. 
If not, the directive is rejected. 


2. If the LUN is valid, check if a valid UCB pointer exists in 
the Logical Unit Table (LUT) for the specified LUN. This 
test determines if the LUN is assigned. If the test fails, 
the directive is rejected. 


3. If steps 1 and 2 are successful, the Executive traces down 
the redirect chain to locate the correct UCB to which the I/O 
operation will actually be directed. 


4. Checks the event flag number (EFN) and the address of the I/C 
Status Block (IOSB). If either is illegal, the directive is 
rejected. Immediately following validation, the subject 
event flag is reset, and the IOSB is cleared. 


5. Obtains 18-words of dynamic storage ana builds the 
device-indefendent portion of an I/O Packet. 


If steps 1 thru 5 succeed, the directive status is set to +l. 


Note that directive rejections in any of the above steps are 
completely transparent to the driver. 


6. Checks the validity of the function being requested and, if 
appropriate, checks the buffer address, byte count, and 
alignment requirements for the specified device. 


If any of these checks fails, the I/G Finish routine (SIOFIN) 
is called. SICFIN sets status and clears tne QIO request 
from the system. 


7. j..IIf the requested function does not recuire a call to. the 
driver, appropriate actions are handled by the Executive and 
SIOFIN is called. 

8. If all I/O Packet checks are positive, the I/Q Packet is 


placed in the driver queue according to the priority of the 
reguesting task. 


1.4.2 Post-Driver Initiation Services 

Once @ driver is given control following an I/O interrupt or by the 
Executive itself, a number of Executive services are available to I/0 
drivers. These services are discussed in detail in Chapter 4. 


There are, however, four Executive services that merit special 
empnasis, Since they are used by virtually every driver in the system: 


l. Interrupt Save (SINTSV); 


Zz. Get Pecket (SGTPKT); 
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3. Create Fork Process (SFORK), and 


4. I/O Done (SIODON). 


1.4.2.1 Interrupt Save (SINTSV) - Interrupts from a device are 
fielded directly by the driver. Immediately following the interrupt, 


the driver is operating at hardware priority level 7 and is, 
therefore, non-interruptible. If the driver needs a lengthy 
processing cycle (greater than 100us) to process the interrupt or 
requires registers, it should call SINTSV; this has the effect of 
stacking external interrupts, altering the hardware priority, and 
providing the calling routine with two free registers to use in 
processing the interrupt. More will be said about S$INTSV in section 
Lies 


1.4.2.2 Get Packet (SGTPKT) - The Executive, after it has queued an 
I/O Packet, calls the appropriate driver at its I/O-initiator entry 
point. The driver then immediately calls the Executive routine S$GTPKT 
to obtain work. When work is available, SGTPKT delivers to the driver 
the highest priority, executable I/O Packet in the driver's I/O queue, 
and sets the SCB status to busy. If the driver's I/O Queue is empty, 
SGTPKT returns a no-work indication. 


If the SCB related to the device is already busy, SGTPKT so informs 
the driver, in which case the driver immediately returns control to 
its caller. 


To the driver writer, note that no distinction exists between no-work 
and SCB busy, since, in either case, an I/O operation cannot be 
initiated. 


1.4.2.3 Create Fork Process (SFORK) - Synchronization of access to 

shared data bases is accomplished via a fork process. When a driver 

needs to access a shared data base, it must do so as a_ fork process; 
ate 


hn Arterar - ea Fark nvrara + 
tne ariver cr s a fork process by calling SFORK. 


1.4.2.4 I/O Done (SIODON) - At the completion of an I/O request, a 
number of centralized checks and additional functions are performed: 


Store status if an IOSB address was specified. 


~ Set an event flag, if one was requested. 


Determine if a checkpoint request can now be honored. 


Determine if an AST should be queued. 


SIODON also declares a significant event, resets the SCB and device 
unit status to idle, and releases the dynamic storage used by the 
completed I/O operation. 
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1.5 PROGRAMMING STANDARDS 


RSX-11M I/O drivers are integral components of the RSX-11M Executive. 
As such, they must follow the same conventions and protocol as the 
Executive itself, if they are to avoid complete disruption of system 
service. This manual has been written to enable programmers to 
incorporate I/O drivers into their systems. Failure to observe’ the 
internal conventions and protocol will result in poor service and 
reductions in system efficiency. 


1.5.1 Process~Like Characteristics of a Driver 


A driver is an asynchronous Executive process. As a process, it 
possesses its own context, allows or disallows interrupts, and 
synchronizes functions within itself (all drivers can be parallel, 
multi-unit, multi-controller) and with other Executive processes 
executing in parallel. 


RSX-11M drivers are small; their small size is made possible by a 


comprehensive complement of centralized services available by calls to 
the Frecutive, and by the availability of an information~dense, highly 
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formalized I/O data structure. 


1.5.2 Programming Conventions 


The programming conventions used by RSX-11M system components are 
identical to those described in Appendix E of the RSX-11 MACRO-11 
Reference Manual. Users preparing I/O drivers for incorporation into 
an RSX-11M system are strongly urged to adhere to these conventions. 


1.5.3 Programming Protocol 


Since an I/O driver accepts interrupts directly from the devices it 
controls, the central Executive relies on the driver to follow strict 
programming protocol so that system performance iS not degraded. 
Furthermore, the protocol ensures that the driver properly distributes 
shared resources according to user-specified priorities. 


When a device interrupts, an I/O driver is entered directly, usually 
calling SINTSV for common’ save and state switching services. (Two 
states, user and system, exist in RSX-l11M; the conventions discussed 
in this manual generally refer to processes running from the system 


state, since drivers operate entirely in system state.) At the 
completion of the services provided by S$INTSV, the interrupt routine 
is again given control to complete the interrupt service. The exit 


routine SINTXT restores the state prior to switching to the system 
state, controls the un-nesting of interrupts, and makes checks on the 
state of the system (for example, it checks if it is necessary to 


Switch tasks). The Fork Processor linearizes access to shared system 
data bases. The details of all these routines will be covered in 
Chapter 4. 


The interrupt vectors in lower memory contain a Program Counter (PC) 
unigue to each interrupting source and a Processor Status Word (PS) 
set with a priority of 7. It is a system software convention to use 
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the low-order four bits of the PS word to encode the controller number 
for multicontroller drivers. When a device interrupt occurs, the 
hardware pushes the current PS and PC onto the currént stack and loads 
the new PC and PS (set at PR7 with the controller number in the 
condition code bits) from the appropriate interrupt vector (the driver 
data base source must set up the interrupt vector). The driver then 
starts executing with interrupts locked out. A driver itself may be 
executing at one of three levels of interrupt sensitivity: 


1. At priority 7 with interrupts locked out; 


2. At the priority of the interrupting source; thus, interrupt 
levels greater than the priority of the interrupting source 
are permitted, or 


3. At fork level which is at priority 0. 


1.5.3.1 Processing at Priority 7 with Interrupts Locked Out - By 
internal convention, processing at this level (interrupt processing 
routine level 1) is limited to 100us. If processing can be completed 
in this time, then the driver simply dismisses the interrupt by 
executing an RTI instruction. The interrupt has been processed and 
dismissed with minimal overhead. 


1.5.3.2 Processing at the Priority of the Interrupting Source - If 
the driver requires additional processing time or the use of general 


purpose registers, it calls the routine SINTSV (Interrupt Save). The 
priority at which the caller is to run immediately follows the call to 
SINTSV. The driver should set this priority level to that of the 
interrupting source. 


SINTSV save uses the specified priority to set up the interrupt 
routine such that it is interruptible by priorities higher than that 
of the interrupting source and conditionally switches to system state 
if the processor is not already in system state. 

The saving of general registers R4 and R5 is done to free these 
registers for the driver. It is an internal programming convention 
that assumes the driver will not require more than two registers 
during interrupt processing. If it does, it must save and restore any 
additional registers it uses. Processing time following the return 
from SINTSV should not exceed 500us*. 


In actual practice, every driver in the system calls SINTSV on: every 
interrupt after executing perhaps 0 or 1 instructions (such as saving 
the PS if more than one controller is being driven). This is due to 
two factors: 


l. It is difficult to service an interrupt without one or _ two 
registers. 


* The 500us period is a guideline. The shorter the period of time a 
realtime executive spends at an elevated priority level, the less 
responsive the system will be to devices of lower priority. MThis is 
especially important if the device being serviced is at the same or 
higher priority than a character-interrupt device such as the DU11, 
which is vulnerable to data loss due to interrupt lockout. 
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2. Most interrupt code may safely be executed at the priority of 
the interrupting source, which is, of course, desirable. 


1.5.3.3 Processing at Fork Level - A driver calls $FORK to meet the 
requirement to become fully interruptible (so as to conform to the 
500us time limit) or to access a shared system data base. SINTSV must 
be called prior to calling SFORK. 


By virtue of calling SFORK, the routine is now at processing level 3 
(interruptible) and its access to system data bases is strictly 
linear. The Fork List is a list of system routines waiting to 
complete their processing, in particular, waiting to access a shared 
system data base. At fork level, all registers are available to the 
process, and R4 and R5 retain the contents they had on entrance to 
SFORK. 


1.5.3.4 Programming Protocol Summary - Drivers are required to adhere 
to the following internal conventions when processing device 
r : 


l. Registers are not available for use unless SINTSV is called 
or the driver explicitly performs save and_ restore 
operations. If SINTSV is called, the use of any registers, 
except R4 and R5, requires that these registers be saved and 


restored. 
2. Non-interruptible processing must not exceed twenty 
instructions, and processing at the priority of the 


interrupting source must not exceed 500us. 


3. All modifications to system data bases must be done via a 
fork process. 


1.6 FLOW OF AN I/O REQUEST 


Following an I/O request through the system at the functional level 
(the level at which this chapter is directed) requires that limiting 
assumptions be made about the state of the system when the QIO 
directive is actually issued. The following assumptions apply: 


l. The system is up and ready to accept an I/O request. All 
required data structures for Supporting devices attached to 
the system are intact. 


2. The only I/O request in the system will be the sample request 
under discussion. 


3. The example will progress without encountering any errors 
that would prematurely terminate its data transfer; thus, no 
error paths will be discussed. 
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The I/O flow proceeds as described below: 


1; 


lb. 


iG. 


{Task issues QIO directive] 


All Executive directives are called via EMT 377. The effect 
of the EMT is to cause the processor to stack the PS and PC 
and pass control to the Executive's directive processor. 


[First level validity checks] 


The QIO directive processor validates the LUN and _ UCB 
pointer. Invalid data results in directive rejection. 


[Redirect algorithm] 


ReAt ean a me en ol ATS ee ee ee mewn hb 
Reairect conmnmana , WLU Girecrive processing traces cnc 


redirect linkage until the target UCB is found. 
[Additional validity checks] 


The EFN is validated as well as the address of the I/O Status 
Block (IOSB). If valid, the event flag is reset and the I/0 
status block is cleared. 


[Obtain storage for and create an I/O Packet] 


QIO directive processing now acquires an 18-word block of 
dynamic storage for use as an I/O Packet. If the 18-words of 
storage are obtained, the directive is accepted. It inserts 
data items into the packet which are subsequently used by 
both the Executive and driver in fulfilling the I/O request. 
Most items originate in the requesting task's Directive 
Parameter Block (DPB). 


[Validate the function requested] 


The function is one of four possible types: 


b) No-op; 
c) File, or 
d) Transfer. 


Control functions, with the exception of Attach/Detach, are 
gueued to the driver. No-op functions do not result in data 
transfers and are performed by the Executive without calling 
the driver. 


A file function may require processing by the file system. 
More typically, the request iS a read or write virtual 
function which is transformed into a read or write logical 
function without requiring file system intervention. When 
transformed into a read or write logical, it becomes a 
transfer function (read and write logical are, by definition, 
transfer functions). 


4a. 


4b. 
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Transfer functions are address checked and queued to the 
proper driver. Then the driver is called at its initiator 
entry point. 


[Driver processing] 
[Reguest work] 


To obtain work, the driver calls Get Packet (SGTPKT). SGTPKT 
will either provide work, if it exists, or inform the driver 
that no work is available, or the SCB is busy; if no work 
exists, the driver returns to its caller. If work is 
available, SGTPKT will set the device controller and unit 
busy, dequeue an I/O request packet, and return to the 
driver. 


{Issue I/0] 


From the available data structures, the driver initiates the 
required I/O operation and returns to its caller. A 
subsequent interrupt may inform the driver that the initiated 
function is complete, assuming the device is’ interrupt 
driven. 


[Interrupt processing] 


When a previously-issued I/O operation interrupts, the 
interrupt causeS a direct entry into the driver, which 
processes it according to the programming protocol described 
earlier. According to the protocol, the driver may process 
the interrupt at priority 7, at the priority of the 
interrupting device, or at fork level. If the processing of 
the I/O reguest associated with the interrupt is still 
incomplete, the driver initiates further I/O on the device 
(4b). When the processing of an I/O reguest is complete, 
SIODON is called. 


[I/O Done processing] 


SIODON removes the device unit and controller busy status, 
queues an AST, if reguired, and determines if a checkpoint 
request pending for the issuing task can now be effected. 
The IOSB and event flag, if specified, are updated, and 
SIODON returns to the driver. The driver branches to its 
initiator entry point looking for more work (step 4a). This 
procedure is followed until the driver finds the queue empty, 
whereupon, the driver returns to its caller. 


Eventually, the processor is granted to another ready-to-run 


process which will issue a QIO directive, starting the I/O 
flow anew. 


La16 
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1.7 DATA STRUCTURES AND THEIR INTERRELATIONSHIPS 


This section presents all the individual control block 
within the system. The following data s 


ta L 
linkages and use 


comprise the complete set for I/O processing: 
1. Task Header; 
2. Window Block (WB); 
3. File Control Block (FCB); 


4. SDEVTB word, the Device Control Block (DCB), and the Driver 
Dispatch Table (DDT); 


5. Unit Control Block (UCB); 

6. Status Control Block (SCB), and 

7. Volume Control Block (VCB). 
Figure 1~4, which will provide the structure for the following 
discussion, shows all the individual data structures and the important 
link fields within them. The numbers on the figure are keyed to the 


text to simplify the discussion and guide the reader through the data 
structures. 


SYSCM 


SDEVHD: 


TASK 
HEADER 
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I/O Data Structure 


The Task Header, one of two independent entries in the I/O 
data structure, is constructed during the task-build process. 
The entry of interest, the Logical Unit Table (LUT), is 
allocated by the Task Builder and filled in at task 
installation. The number of LUT entries is established by 
the UNITS= keyword option and places an upper limit on the 
number of device units a task may have active simultaneously. 
Each LUT entry contains a pointer to an associated UCB, and a 
pointer to a Window Block if a file is accessed. 


A Window Block (WB) exists for each active access to files on 
a mounted volume. Its function is to speed up the process of 
retrieving data items in the file; entries in a WB consist 
mainly of pointers to contiquous areas on the device where 
the file resides. 


volume has an 
The file system uses 


Each uniguely-opened file on a mounted 
associated File Control Block (FCB). 
the FCB to control access to the file. 


SDEVTB is a word located in system common (SYSCM) and is’ the 
other independent entry in the I/O data structure. SDEVTB 
points to a singly~linked, uni-directional list of Device 
Control Blocks (DCB's). Each device type in a system has an 
associated DCB. At least one DCB exists per device type. 
The DCB list is terminated by a zero in the link word. 

Linked to each DCB is a Driver Dispatch Table (DDT). The DDT 


contains the addresses 


points. 


of the driver's four callable entry 
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5. A key data structure is the Unit Control Block (UCB). All 
the UCB'sS associated with a DCB appear in consecutive memory 
locations. During internal processing of an I/O request, R5 
contains the address of the related UCB, and it is via 
pointers in the UCB that other control blocks in the data 
Structure are accessed. In particular, the UCB contains 
pointers to the DCB, SCB, VCB, and to the UCB to which it may 
have been redirected. If a Redirect command has not been 
issued for the device-unit, the UCB redirect pointer points 
to the UCB itself. A driver services a fixed set of UCB's. 
When servicing a request for one of its UCB's, it is unaware 
of whether I/O was issued directly to the UCB or whether it 
was issued to a UCB redirected to its UCB. 


99) 


6. One Status Control Block (SCB) exists for each controller in 
a system. A unique SCB must exist for each controller/device 
unit capable of performing parallel I/O. The SCB_ contains 
the fork block storage required when a driver calls SFORK to 
transfer itself to the fork processing level. The I/0 
request queue listhead is also contained in the SCB. 


7. One Volume Control Block (VCB) exists for each MOUnted volume 
in a system. The VCB is used to maintain volume-dependent 
control information. It contains pointers to the File 
Control Block (FCB) and Window Block (WB) used to control 
access to the volume's index file. (The index file is a file 
of file headers.) The WB for the index file serves the same 
function as the WB for a user file. All unigue FCB's for a 
volume form a linked list emanating from the index file FCB. 
This linkage aids in keeping file access time short. 
Further, since the window which contains the mapping pointers 
is variable in length, the user can increase file access 
speed by adding more access pointers (greater speed requires 
more main memory) to whatever extent his application 
requires. 


The writer of a conventional driver never manipulates the entire 1/0 
data structure. In fact, he is almost exclusively involved only with 
the I/O Packet, the UCB, and the SCB. The entire structure has been 
presented to add depth to the driver writer's understanding of the I/0 
system, to emphasize the relationships among individual control 
blocks, and to further clarify the role a given driver fulfills in the 
processing of an I/O request. 


CHAPTER 2 


INCORPORATING USER-WRITTEN DRIVERS INTO RSX-11M 


2.1 INTRODUCTION 


Though explicit details for writing a driver have not been presented, 
enough conceptual information now exists to consider incorporating a 
user driver into a system. This follows from the fact that many 
considerations for writing a driver are most easily presented within 
the context of the process followed for installing it. 


The reader is already assumed to be familiar with the RSX-11M System 
Generation Manual. 

the 
the relevant co 
driver. 


2.2 OVERVIEW 


The user who has decided to add a driver to RSX-11M has concomitantly 
shared the responsibilities for the integrity of the Executive. 
Errors in this code can easily cause a system failure and bring to a 
halt all user service. 


nvolved in creating and installing a user-written 
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1. Bootstrap the source disk and run Sysgen Phase l. 
2. Bootstrap the object disk. 


3. Create the assembly source for the driver and its associated 
data structures. 


4. Run Sysgen Phase 2. 
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At the completion of Sysgen Phase 2, the user has a system with the 
user-written driver integrated into it. Since it is anticipated that 
a debugging seguence will be required to shake down the driver, the 
following sequence will result in an updated driver being incorporated 
into the existing system: 
1. Correct and re-assemble the driver and/or data structures. 


2. Run the Librarian to replace the old object modules in 
RSX11M.OLB with the repaired ones. 


3. Rebuild the Executive using RSXBLD.CMD. 
4. Using Virtual MCR, rebuild the system. 
5. Bootstrap the system. 
When adding a user-written driver to the system, the driver may be 


assembled to include padding space for possible expansion during the 
debugging process. 


2.3 INCORPORATING A DRIVER ~— DETAILS 


2.3.1 Creating the Data Structure 


The data structures associated with I/O drivers will be detailed in 
Chapter 3. Of the structures discussed, only three require assembly 
source: 


1. The DCB; 
2. UCB's, and 
3. SCB's. 


Within these control blocks, only those items which are static or 
reguire initialization are supplied in the source description. Listed 
below is an overview of the data fields the driver writer will be 
required to supply in the assembly source of his driver's data 
structure. 


2.3.1.1 Reguired Device Control Block (DCB) Fields - The required DCB 
fields are described below: 


D.LNK Link to next DCB. 


This field will be zero if this is the last DCB. Lk 
the user is incorporating more than one usSer-written 
driver at one time, then this field should point to 
another DCB in the DCB chain. 


D.UCB Address of the first UCB associated with this DCB. 


D.NAM Two-character ASCII generic device name. This name 
must be unigue. 


D.UNITE 


Es UCBL 


D..DSP 


D.MSK 
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Highest and lowest unit numbers controlled by this DCB. 
Length of a UCB. 


If a given DCB has multiple UCB's, all UCB's must be of 
the same length. 


Address of the driver dispatch table. 


The dispatch table is located within the driver code. 
This field will contain a global reference to the label 
associated with this table. 


I/C function masks 


The user must supoly bit-by-bit mapping for these four 
I/O function masks. Note that the format of the mask 
words is split into two groups of four words. 
Functions 0-15 are covered by the first group, and 
functions 16-31 by the second. 


2.3.1.2 Required Unit Control Block (UCB) Fields - The required UCB 
fields are described below: 


U.DCB 


U.RED 


UeGrL 


U.STS 


U.UNIT 


UseF2 


Backpointer to the associated DCB. 


Initially contains the address of this UCB (li.e., 
redirect pointer). 


Control bits that must be established by the driver 
writer with tne UCB source. 


Unit status byte. 
Physical unit number serviced by this UCB. 


Unit status byte extension. 


Driver dependent. 

Driver dependent. 

Default buffer size. 

Address of the SCB for this UCB. 


TCB address of attached task. 
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2.3.1.3 Required Status Control Block (SCB) Fields - The required SCB 
fields are described below: 


S.LHD I/O Queue listhead. 

S.PRI Priority of interrupting source. 

S.VCT Interrupt vector address divided by 4. 

S. ITM Initial timeout count. 

S.CON Controller index (i.e., controller number multiplied by 
2)% 

S.STS Controller status. 

S.CSR Address of control and status register. 


2.3.1.4 Source Format of the Cata Structure - A single DCB can 
service multiple UCB's and SCB's. The existence of multiple UCB's and 
SCB's is determined by the actual device subsystem being supported by 
a given driver on the user's operational hardware configuration. 
Figures 1-2 and 1-3 illustrate possible DCB, UCB, and SCB_~ structural 
relationships. Typically, in writing a data structure source 
(DEC-supplied RSX-l11M drivers use this scheme), the DCB is_- placed 
first, followed by the UCB(s), followed by the SCB(s). 


2.3.2 Creating the Driver Source Code 
Creating the source code to drive a device involves the following: 
l. Thorough reading and understanding of this manual; 


2. Detailed familiarization with the physical device and its 
operational characteristics; 


3. Determining the level of Support required for the device; 


4, Creating the data structure source code for the device; 
5. Determining actions to be taken at the five driver entry 
pots. 
a. Initiator; 


b. Cancel I/O; 
c. Timeout; 
d. Powerfail, and 
e. Interrupt. 
6. Creating the driver source code. 


Source code for the driver and data structure should be created on the 
object disk under UIC [200,200]. 
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2.3.3 Incorporating the User-Written Driver 


Incorporating a driver is accomplished via the standard system 
generation process. Phase 1 of system generation includes queries 


which condition Phase 2 for user-written driver inclusion. 
Specifically, the query 


ARE YOU PLANNING TO INCLUDE A USER WRITTEN DRIVER? [Y/N]: 
if answered affirmatively, results in a second query 
WHAT IS THE ADDRESS OF THE HIGHEST DEVICE INTERRUPT VECTOR? [0]: 


The answer to which is reguired so Phase 1 can allocate sufficient 
vector space to avoid run-time destruction of the system stack. 


a) 
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*DO YOU WISH TO ADD USER WRITTEN DRIVER(S) TO THE EXEC? [Y/N]: 


is posed. If the answer is affirmative, then subsequent dialog guides 
the driver writer through the process of adding his driver to the 
generated system. Operations performed include assembly of the driver 
and its data structure, inclusion of the resultant object modules into 
the executive object module library, and editing of the RSX-11M _ task 
build command file. 

The following sample dialog illustrates the addition of a driver for 
device XxX. All user responses are underlined. The notation [1,2x] 
indicates that the appropriate UIC is to be substituted, viz., [1,20] 
for an unmapped system and [1,24] for a mapped system. 


>* DO YOU WISH TO ADD USER WRITTEN DRIVER(S) TO THE EXEC? [Y/N]:¥ 


>SET /UIC=[200,200] 


ay 

>; WE WILL PAUSE WHILE YOU ASSEMBLE YOUR DRIVER(S) AND USRTB 
>; MODULE. THE EXEC ASSEMBLY PREFIX FILE RSXMC.MAC IS ALREADY 
>; LOCATED UNDER UIC [200,200]. ASSUMING YOUR DRIVER(S) NAME IS 
>; XXDRV, WHERE XX IS THE DEVICE NAME (E.G., DK) THE FOLLOWING 
>; COMMANDS WILL ASSEMBLE THE DRIVER(S) AND THE USRTB MODULE. 
ae 

>; >RUN SMAC 

>; MAC>XXDRV=[1,1]EXEMC/ML, [200,200] RSXMC,XXDRV 

>: MAC >USRTB=[1,1]EXEMC/ML, [200,200]RSXMC,USRTB 

>: MAC>“Z 

>? 

> 

AT. -- PAUSING. TC CONTINUE TYPE "RES ...AT." 

>RUN SMAC 


MAC>XXDRV=[1,1]EXEMC/ML, [200,200] RSXMC, XXDRV 
MAC >USRTB=([1,1]EXEMC/ML, [200,200] RSXMC,USRTB 


MAC>72 
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PRES ss Als 
AT. -- CONTINUING 


NOW YOU MUST ADD YOUR DRIVER(S) AND USRTB MODULE 
TO THE EXEC OBJECT MODULE LIBRARY. THE FOLLOWING IS AN EXAMPLE: 


LBR>RSX11M/RP=[200,200] XXDRV,USRTB 
LBR>“Z 

>i 

>SET /UIC=[1, 2x] 

>LBR 


LBR>RSX11M/RP=[200, 200] XXDRV,USRTB 


LBR>“Z 


YOU MUST NOW ADD COMMANDS TO INCLUDE YOUR DRIVER(S) AND USRTB 
MODULE INTO THE EXEC BY EDITING THE EXEC TASK BUILD COMMAND FILE. 
TO ADD DRIVER(S), INSERT COMMANDS OF THE FORM: 


se se Ne Ne 


[1,2x] RSX11M/LB: XXDRV 


INTO THE COMMAND FILE IN THE PLACE WHERE THE 

OTHER DRIVERS ARE REFERENCED. XXDRV REPRESENTS THE NAME OF 
YOUR DRIVER(S). IN ADDITION, LOCATE THE LINE IN WHICH THE 
MODULE SYSTB IS REFERENCED AND ADD A REFERENCE TO YOUR 
USRTB MODULE IMMEDIATELY AFTER IT. E.G.: 


[1,2x] RSX11M/LB: LOADR: NULTK: SYSTB: USRTB:SYTAB: INITL 
THEN LOCATE THE LINE: 


GBLDEF=S$USRTB: 0 


~we ~e we we Oe A MO MH Ne NO Ne Ne Ne FO Ne fe 


AND DELETE IT. 


VNMVV VV VV VV VV VN VV VV VV VV 


~e 


>EDI RSXBLD.CMD 

[PAGE a] 

+P TTDRV 
[1,2x]RSX11M/LB:TTDRV 
en 
[1,2x]RSX11M/LB: XXDRV 


*/ 

[1,2x] RSX11M/LB: LOADR: NULTK: SYSTB:SYTAB:INITL 
*C/SYSTB/SYSTB:USRTB/ 

[1,2x] RSX11M/LB: LOADR: NULTK: SYSTB:USRTB:SYTAB: INITL 
*PL SUSRTB 


GBLDEF=SUSRTB:0 


This completes the user-written driver section of Phase 2, which then 
continues. 


INCORPORATING USER-WRITTEN DRIVERS INTO RSX-11M 
2.4 DRIVER DEBUGGING 


Since the protection checks afforded user programs are not available 
to system modules, driver errors will be more difficult to isolate 
than user program errors. But conventional drivers, being modular and 
short, should be easily debugged. The following three sections 
describe a set of debugging tools and guidelines that should simplify 
the driver debugging process. 


Section 2.4.1 describes how to re-incorporate a driver into a system 
after a fault has been discovered. Section 2.4.2 describes the 
Executive Debugging Tool, and Section 2.4.3 provide some general hints 
for isolating faults in Executive software (of which drivers are a 
subset). 


2.4.1 Rebuilding and Re-incorporating the User Driver 


Rebuilding and re-incorporation involves five steps: 


1. Correction and re-assembly of the driver and/or device data 
structures; 


2. Updating the Executive object module library; 
3. Rebuilding the Executive; 
4, Running Virtual MCR to rebuild the system, and 


5. Bootstrapping the new system. 


2.4.1.1 Re-Assembly - Assuming that the object system has been 
bootstrapped, appropriate volumes have been MOUnted, and the source 
code for the user driver and/or device data base has been updated, 
then: 


>RUN SMAC/UIC=[200, 200] 


MAC>XXDRV=E!1, LIEXEMC/ML, [200,2001R TNC SESE 
B 


S 
MAC >USRTB=[1,1]E 1] EXEMC/ML, [200, 200] RSX USRT 


MAC>*Z 


will effect the re~assembly of both the driver and data base. 


2.4.1.2 Updating the Executive Object Module Library - After 


re-assembly of the user driver and/or data base, the Executive object 
module library must be updated. The following commands will 
accomplish this: 


>RUN SLBR/UIC=[1,2x]* 


LBR>RSX11M/RP=[200, 200] XXDRV,USRTB 
LBR>”Z 


* "x' is a 'O' for an unmapped syster and '4' for & marred system. 
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2.4.1.3 Rebuilding the Executive - Since an updated driver is to be 
inserted, the Executive, of which the driver is a part, must be 
relinked. To do this, enter the following commands: 

>RUN STKB/UIC=[1,2x]* 

TKB>@RSXBLD 

TKB>"Z 


>RUN SPIP/UIC=[1,5x]* 


PIP>RSX11M.SYS/NV=RSX11M. TSK 


PIP>"Z 


2.4.1.4 
using 
ready for bootstrapping. 


Incorporating Tasks into the System - Run Virtual MCR _ (VMR) 
the dialog shown as a guide. On completion, the new system is 


The general procedure to follow is: 


1. Establish system partitions; 
2. Release all unused space to the dynamic storage region; 
3. Install tasks (at least FCP, INS, MOU, and MCR); and 


4. Exit from Virtual MCR and boot in the new system. 


VMR Example: 


>RUN SVMR/UIC=[1,5x]* ! RUN VIRTUAL MCR 

ENTER FILENAME: KSX11M.SYS ! VMR PROMPTS FOR FILE NAME 
VMR>SET /MAIN=SYSFAR: 1300:100: TASK SET UP SYSTEM PARTITION 
VMR>SET /MAIN=PAR14K: 400: 700: TASK SET UP 14K PARTITION 
VMR>SET /SUB=PAR14K:GEN: a0n: 400 ! SET UP 8K SUB PARTITION 


— ¢0m Ome 


>BOO 


[1,5x]RSX11M 


Oe 


bootstrapped with the MCR Boot command, 


for an unmapped system and 


2-8 


as snown below: 


'4' for a mapped system. 


VMPOSET SET /POOL=400 400 ADD FREE SPACE TO POOL 
VMR>INS BOO INSTALL BOOT 
VMR>INS DMO ! INSTALL DISMOUNT 
VMR>INS FCP ! INSTALL FILE SYSTEM 
VMR>INS IND ! INSTALL INDIRECT FILE PROCESSOR 
VMR>INS INI ! INSTALL INITVOLUME 
VMR>INS INS ! INSTALL INSTALL 
VMROINS MCR ! INSTALL MCR 
VMR>INS MOU ! INSTALL MOUNT 
VMR>INS SAV ! INSTALL SAVE 
VMR>INS TKN ! INSTALL TASK TERMINATION TASK 
VMR>INS UFD ! INSTALL USER FILE DIRECTORY BUILDER 
VMR>"Z ! EXIT FROM VIRTUAL MCR 
2.4.1.5 Bootstrapping the New System - The new system may now be 
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2.4.2 RSX-11M Executive Debugging Tool 


An interactive debugging tool has been developed for RSX-11M to aid in 
the debugging of executive modules, 1/0 drivers, and interrupt service 
routines. This debugging aid is called XDT and is a version of RSX-1l 
ODT, which does not contain the following features and commands: 

No $M ~— (MASK) register 

No $X - (Entry Flag) registers 

No $V - (SST vector) registers 


No $D - (I/O LUN) registers 


No SE - (SST data) registers 

No E - (Effective Address Search) command 
No F = (Fill Memory) command 

No N - (Not word search) command 

No V - (Restore SST vectors) command 

No W - (Memory word search) command 


The X (Exit) and P (Proceed) commands have also been changed. The xX 
command causes a jump to the crash reporting routine, and the P 
command will permit the user to proceed if an unknown breakpoint is 
encountered. 


Other than the omitted features and the change in the definition of 
the xX and P commands, XDT is command-compatible with RSX-ll ODT, and 
the RSX-11 ODT Manual may be used as a guide to its operation. 


XDT 


may be included in a system during Phase 1 of system generation. 
The que 


rve 
+J¥e 


u 
DO YOU WANT TO INCLUDE THE EXECUTIVE DEBUGGING TOOL? [Y/N]: 
is posed. If the answer is affirmative, then xXDT is automatically 
included in the generated system. When the resultant system is 
bootstrapped, XDT gains control and types: 

XDT: <system version> 

followed by the prompting symbol 

XDT> 
on the console terminal. Breakpoints may be set at this time, and 
then a G command may be given, returning control to the RSX-11M 


Executive initialization code. Whenever a breakpoint is reached, a 
printout similar to that of RSX-11 ODT will occur. 
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A forced entry to XDT can be executed at any time from a _ privileged 
terminal via the MCR Breakpoint (BRK) command. Thus, the normal 
procedure is to type G when the system is bootstrapped without setting 
any breakpoints. When it becomes necessary to use XDT, the MCR 
Breakpoint command is executed, causing a forced breakpoint. XDT then 
prints: 


BE:xXXxXXXx 
followed by the prompting symbol 
XDT> 


on the console terminal. Breakpoints and/or other XDT commands’ may 
then be executed. System operation may be continued by typing the P 
(Proceed) command to XDT. 


Note that XDT runs entirely at priority level 7 and does not interfere 
with user level RSX-ll ODT. In other words, user level RSX-1l1l ODT can 
be in use with several tasks, while xXDT is being used to debug 
Executive modules. 


All XDT command I/O is done via the console terminal; and the L 


(List 
Memory) command can list on either the console or the line printer. 


2.4.3 Fault Isolation - Some General Hints 


2.4.3.1 Introduction - Adding a user-written driver carries with it 
the risk of introducing obscure bugs into an RSX-11M system. Since 
the driver runs as part of the Executive, these bugs are often 
difficult to diagnose. It is extremely important that the driver 
writer develop the skills and discipline needed to rapidly isolate the 
source of a system failure. 


2.4.3.2 Fault Classifications - Four culprits can be identified when 
the system faults: 


l. A user-state task has faulted such that it causes the system 
to fault; 


2. The user-written driver has faulted such that it causes’ the 
system to fault; 


3. The RSX-11M system software itself has faulted, or 
4. The host hardware has faulted. 


The immediate action on the part of the driver-writer subject to one 
of these errors is to determine which of these four cases is the 
source of the fault. Of prime concern will be the procedures’ which 
may help the driver writer uncover the fault source. The repair of 
the fault itself is assumed to be the driver writer's responsibility. 
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Faults manifest themselves in roughly three ways (they are listed here 
in order of increasing difficulty of isolation): 


1. The system displays the CRASH printout and halts or, if XDT 


yr 


has been included, an unintended trap to XDT occurs. 
2. The system halts but displays nothing. 


3. The system is in an unintended loop. 


2.4.3.3 Immediate Servicing - RSX-liM can be built to contain 
resident crash reporting and panic dump routines; the following 


discussions assume the existence of such a system. (Note that the 
minimal system will not have space for these routines). Section 2.5 
contains sample listings from both crash and panic dump routines. 


The immediate aim, regardless of the fault manifestation, is_ to 
initiate the crash reporting and panic dump routines. 


CASE 1 - The system has trapped to XDT: 


The trap may or may not be intended (e.g., a previously set 
breakpoint). If it is not intended, type the X command, causing XDT 
to exit to the crash reporting routine; if, however, the source of 
the problem is suspected (for example, a recent coding change), then 
pertinent data structures and code may be examined using XDT. 


CASE 2 - The System Has Displayed the Crash Printout: 


In this case, all the basic information describing the state of the 
system has been displayed. The actual Crash printout will be 
described after learning how to invoke Panic Dump for cases 3 and 4 
(see below). 


CASE 3 - The System Has Halted - No Information Displayed: 


Before taking any action, preserve the current PS and PC and_ the 
pertinent device registers (i.e., examine and record the information 
these registers contain). The procedure depends on the particular 
PDP-ll processor. Consult the appropriate PDP-1ll Processor Handbook 
for details. 


After obtaining the PS and PC, invoke the Panic Dump Routine by 
entering 40(8) in the switch register, depressing LOAD ADDR, and then 
START. 


The value 40(8) is the address of a JMP to the Panic Dump Routine in 
all RSX-11M systems. 


The Panic Dump Routine saves registers RO through R6 and then halts, 
awaiting dump limits to be entered via the console switch register. 
The PS is cleared when START is depressed, and the original PC is 
destroyed; thus, the importance of recording these vital pieces of 
debugging information before initiating the Panic Dump Routine’ should 
be recognized. 
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Dumps of selected blocks of memory may be obtained using the following 
procedure: 


1. Enter the low dump limit in the console switch register and 
depress CONT. The processor will immediately halt again. 


2. Enter the high dump limit in the console switch register’ and 
depress CONT. The dump will begin on the device whose CSR 
address is DSSBUG (uSually 177514, which is the line 
printer). The actual value of DSSBUG is determined during 
system generation when answering the panic dump guestion. At 
the end of the dump, the processor will again halt, awaiting 
the input of another set of dump limits. 


To reach the same status arrived at with crash reporting in 
Case 2 above, enter the dump limits 0-520(8) when the panic 
dump routine first halts. This will dump the system_ stack 
and the general registers. The limit 520(8) changes if the 
highest interrupt vector is above 400(8). The actual upper 
limit is always the value of the global symbol SSTACK and may 
be obtained from the module LOWCR in the Executve memory 
allocation map. 


CASE 4 - System Is in an Unintended Loop: 
Proceed as follows: 
1. Halt the processor 


2. Record PC, PS, and any pertinent device registers, as in case 
3 above. 


After recording the PS and PC, the driver-writer may want to step 
through a number of instructions in an attempt to locate the loop. 


After the attempt to locate the loop, transfer to the panic dump 
routine as in Case 3. 


This brings us to an equivalent status for the three fault situations. 


2.4.3.4 Other Pertinent Fault Isolation Data - Before proceeding with 
the task of locating the fault, the driver-writer is strongly advised 
to dump system common (SYSCM). This can be accomplished by looking 
for the module SYSCM in the Executive memory allocation map and 
entering the appropriate limits to the Panic Dump Routine. SYSCM 
contains a number of critical pointers and listheads. 


In addition, the driver-writer should dump the dynamic storage region 
and the device tables. The dynamic storage region is the module INITL 
and the device tables are in SYSTB. 
The driver-writer now has: 

PS 

PC 


The Stack 
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RO through R6 
Pertinent device registers 
The dynamic storage region 
The device tables, and 
System common. 


This data is a minimal requirement for effective fault isolation. 


2.4.3.5 Fault Tracing - Three pointers in SYSCM are critical in fault 
tracing. These pointers are described below: 


SSTKDP - Stack Depth Indicator 
This data item will indicate which stack was being used at _ the 


time of the crash. As will be seen, this plays an important role 
in determining the origin of a fault. The following values 


apply: 

+] - User (task state) stack 

0 or less - System stack 
If the stack depth is +l, then the user has managed to crash the 
system. In a system with brickwall protection (for example, the 
mapped RSX-11M system), the non-privileged user should not be 
able to crash the system. 

STKTCB - Pointer to the Current Task Control Block (TCB) 

This is the TCB of the user level task in control of the CPU. 


SHEADR - Pointer to the Current Task Header. 


Locating the task header provides additional data. The first 
mA rA an thn hanAar Se tha sr:4eanr Pe aewbhanArb Knrntntar thn laete faimaAa Tt 
wuLlu Lil LIC LIT AVUoL ip LIC uDpeLl PD DPLALCKA vYUL GLeL Lilt 1tanoe CLING itv 
was saved. If the user branches wildly into the Executive, it 


will terminate the user task, but the system will continue to 
function (possibly erroneously). Knowing the user's stack 
pointer provides one more link in the chain which may lead to the 
resolution of the fault. 


The header (as pointed to by S$HEADR) also contains the last saved 
register set, just before the header guard word, which is the 
last word in the header and is pointed to by H.GARD. 


H.NLUN 


H.GARD 


H.»HDLN 
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| 


LENGTH IN BYTES 


Figure 2-1] 
Unmapped System Header 


27T4 
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Figure 2-2 
Mapped System Header 


A. Tracking Faults Following Automatic Display of System State (Cases 
1 and 2): 


he system stack pointer. Usually an Executive failure 


oe 
of an SST type trap within the Executive. 


If an SST does occur within the Executive, then the origin of the cail 
on the crash reporting routine will be in the SST service module. 
(The crash call is initiated by issuing an IOT at a stack depth of 
zero or less). 


A call to crash also occurs in the Directive Dispatcher when an EMT 
was issued at a stack depth of zero or less, or a trap instruction was 
executed at a depth of less than zero. The stack structure in the 
case of an internal SST fault is shown in Figure 2-3. 
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RO 


| NUMBER OF BYTES | =<————. sp 


Figure 2-3 
Stack Structure - Internal SST Fault 


The fault codes are: 


0 7;ODD ACDRESS AND TRAPS TO 4 

25 ;MEMORY PROTECT VIOLATION 

4. ;BREAK POINT OR TRACE TRAP 

6 ;1O0T INSTRUCTION 

8. ; ILLEGAL OR RESERVED INSTRUCTION 
10. ;NON RSX EMT INSTRUCTION 


12. ;TRAP INSTRUCTION 

ba 711/40 FLOATING POINT EXCEPTION 
LO< ;SST ABORT-BAD STACK 

18. 7;AST ABORT-BAD STACK 

20. ;ABORT VIA DIRECTIVE 

22. 7TASK LOAD READ FAILURE 

24. ;TASK CHECKPOINT READ FAILURE 
26. ;TASK EXIT WITH OUTSTANDING I/O 
20% ;TASK MEMORY PARITY ERROR 


The PC points to the instruction following the one which caused the 


SST failure. The number of bytes is the number of bytes that are 
normally transferred to the user stack when the particular type of SST 
occurs. If the number is 4, then just the PS and PC are transferred 


and there are no SST parameters. 


If the failure is detected in SDRDSP, the stack is the same as’ Figure 
2-3, except the number of bytes, SST fault code (the fault codes are 
listed above), and SST parameters are not present. The crash report 
message, however, will indicate that the failure occurred in SDRDSP. 
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There is one SST-type failure, stack underflow, that will not have the 
stack structure of Figure 2-3. To determine where the crash occurred, 
first establish the stack structure; this can be deduced by the value 
of the stack pointer (SP) and the contents of the top word on the 
stack. If the stack structure is that of Figure 2-3, then the failure 
occurred in SDRDSP, or waS a normal SST crash. If the stack structure 
is determined to be that of Figure 2-4, then a non-normal SST crash 
has occurred. 


Figure 2-4 
Stack Structure - Non-Normal SST Fault 


Non-normal SST failures occur when it is not possible to push 
information on the stack without forcing another SST fault. When this 
occurs, a direct jump to the crash reporting routine iS made rather 
than an IOT crash. The PS and PC on the stack are those of the actual 
crash, and the address printed out by the crash reporting routine is 
the address of the fault rather than the address of the IOT that 
crashes the system. Note that the crash reporting routine removes the 
PC and PS of the IOT instruction from the stack, which in this case is 
incorrect. Thus, the stack pointer will appear to be 4 greater than 
it really is (i.e., aS in Figure 2-4). 


The driver writer now has all the information needed to isolate the 
cause of the failure. From this point on, one must rely on personal 
experience and a knowledge of the interaction between the driver and 
the services provided by the Executive. 


B. Tracking Faults When the Processor Halts Without Providing Fault 
Display: 


Tracking starts with an examination of SSTKDP, STKTCB, and S$HEADR. 
The difficulty in tracking failures in this case is that the system 
stack is not directly associated with the cause of a failure. 


By examining $STKDP, one can determine the system state at the time of 
failure. If it was in user state, the next step is to examine the 
user's stack. The examination process focuses on scanning the stack 
for addresses which may turn out to be subroutine links which will 
ultimately lead to a thread of events isolating the fault. This is 
essentially the same aim in looking at the system stack if S$STKDP is 
zero or less. 


Frequently, a fault will occur such that the SP points to Top of Stack 
(TOS) +4. This results from issuing an RTI when the top two items on 
the stack are data; this will result in a wild branch, then, most 
probably, a halt. Figure 2-5 shows a case, where two data items are 
on the stack when the programmer executes an RTI. TOS points to a 
word containing 40100. Suppose that location 40100 contains a halt. 
This indicates that the original SP was four bytes below the final SP, 
and fault tracing should begin from the previous SP. 
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~«— SP 


40100 |~— SP 


Figure 2-5 
Stack Structure ~- Data Items on Stack 


This type of fault also occurs when an RTS instruction is executed 
with an inconsistent stack. However, in this case SP will point to 
TOS+2. 


A scan of the contents of the general registers may give some hint as 
to the neighborhood in which a fault (or the sequence of events 
leading up to the fault) occurred. 


If the fault occurred in a new driver, a frequent source of clues is 
the buffer address and count words in the UCB (U.BUF, U.BUF+2, U.CNT), 
as are the activity flags (US.BSY and S.STS). Other locations in both 
the UCB and SCB may also provide information that may help locate the 
source of the fault. 


C. Tracking Faults When an Un-Intended Loop Has Occurred: 


After halting the processor, the same state exists as in the preceding 
section. Some specific suggestions are to check for a stack overflow 
loop. Patterns of data successively duplicated on the stack indicate 
a stack looping failure. 


D. Additional Hints: 


Also of value is the current (or last) I/O Packet, the address of 
which is found in S.PKT of the SCB. The packet function (I.FCN) will 
define the last activity performed on the unit. 


If trouble occurred in terminating an I/O reguest, a scan of the 
system dynamic memory region may provide some insight. This region 
Starts at the address contained in SCRAVL, a cell in SYSCM. Since all 
I/O packets are built in system dynamic memory, when they are 
successfully terminated, their memory is returned to the dynamic 
memory region. Following the link pointers in this region may reveal 
whether or not I/O completion proceeded to that point. A freguent 
error for an interrupt-driven device is to terminate an I/O Packet 
twice when the device is not properly disabled on I/O completion and 
an unexpected interrupt occurs. This ultimately produces a double 
de-allocation of the same packet memory. Double de-allocation of a 
dynamic buffer in RSX-11M causes a loop in the module SDEACB on the 
next de-allocation (of a block of higher address) after the second 
de-allocation of the same block. At that time, R2 and R3 both contain 
the address of the I/O Packet memory which has been doubly 
de-allocated. 
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2.5 SAMPLE OUTPUT FROM CRASH AND PANIC DUMP ROUTINES 


2.5.1 Crash Output 
A sample of Crash output is shown below: 
SYSTEM CRASH AT LOCATION 047622 
REGISTERS 

RO=000340 R1=177753 R2=000353 R3=000000 


R4=000004 R5=046712 SP=000472 PS=000340 


LOCATION CONTENTS 


000472 000004 
000474 000000 
000476 001514 
000500 000340 
009502 177753 
000504 000353 
000506 000000 
000510 000000 
000512 057750 
000514 002504 
000516 030011 
000520 100340 
900522 000340 
00524 056446 
000526 000000 
000530 102144 
000532 000000 
000534 101376 
000536 101372 
000540 102022 


NNNSAD 1I7NOAAN 
U tivvueuyv 


VVUY Te 


2.5.2 Panic Dump Output 


A portion of the output from Panic Dump is shown below. Output is in 
three line groupings. In the left-hand column, two addresses are 
shown. The first address is the absolute address; the second address 
is the dump relative address. The first line in a 3-line group is the 
octal word value; the second line is the two octal byte values of the 
word; the third line contains the ASCII representation of the bytes. 
The ASCII representations are reversed to improve’ readability. The 
first output grouping from Panic Dump displays, proceeding from right 
to left, PS, RO, Rl, R2, R3, R4, R5, and the SP. 


000544 
000000 


000000 
000000 


000020 
000020 


000040 
000040 


000060 
000060 
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000000 000066 
000 000 114 076 QO00 066 
“@ “@ 6 “@ 

022646 045770 
045 246 000 340 113 370 

& % “@ K 

045776 011124 
113 376 022 124 

K T “R 

000167 000001 

000 167 000 O01 
“@ “A “@ 

035444 034034 
073 044 070 034 

S ; ‘\ 8 


000000 
000 000 
“ee 


000340 
000 340 
“@ 


000340 
000 340 
*@ 


000001 
000 OO1 
“A “@ 


000340 
000 340 
“@ 


000000 
000 000 


 @ @ 


045770 
113 370 
K 


045770 
113 370 
K 


000000 
000 000 
“e *@ 


032776 
065 376 
5 


000000 
000 000 
e@ “e 


000340 
000 340 
“@ 


000340 
000 340 
“@ 


000000 
000 000 
“@ *@ 


000340 
000 340 
“@ 


000000 
000 000 
@e “@ 


045770 
113.370 
K 


050500 
121 100 
@ Q 


000000 
000 000 
“e@ *@ 


032402 
065 002 
“B 5 


045316 
Lr2: 316 
N J 


000340 
000 340 
“@ 


000340 
000 340 
“@ 


000353 
000 353 
“@ 


000340 
000 340 


“@ 


CHAPTER 3 


WRITING AN I/O DRIVER ~- PROGRAMMING SPECIFICS 


In Chapter 1, overviews were given for: 
Data structures; 
Executive services, and 
Programming protocol. 


In this chapter, the details for the data structures and Executive 
services are given. The protocol coverage in Chapter 1 was, however, 
detailed enough to make further elaboration of programming protocol 
unnecessary. 


3.1 DATA STRUCTURES 


Of all the control blocks in the I/O data structure, only four are of 
direct concern to a driver writer: 


1. The I/O Packet; 


2. The DCB; 


3. The UCB, and 
4. The SCB. 


Although the data structures contain an abundance of data pertaining 
to input/output operations, drivers per se are involved only with a 
subset of this data. Most of the data which requires the driver 
writer's attention is supplied in the data structure source code, and 
is not referenced during driver execution. Such an item is classified 
as: 


<initialized, not referenced>* 


* The first field states whether the field is initialized in the data 
structure source, and the second field gives the typical access at 
execution time. 


WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS 
Fields supplied statically in the source code at the creation of the 
data structure, and subsequently referenced during driver execution, 
are classified: 
<initialized, read-only>. 
Fields set up during driver execution are classified: 
<not initialized, read-only> 
This form implies that either an agent other than the 
driver has established the field or that the driver has 
set it up once and references it read-only thereafter. 
or: 


<not initialized, read-write>. 


Fields which do not involve the driver writer at any level are 
classified 


<not initialized, not-referenced>. 


These classifications cover most~likely cases, since exceptions do 
exist and are appropriately noted. 


3.1.1 The I/O Packet 


Figure 3-1 is a layout of the 18-word I/O Packet which is constructed 
and placed in the driver I/O queue by QIO directive processing and 
subsequently delivered to the driver by a call to S$GTPKT. Figure 3-2 
is the DPB from which the I/O Packet is generated. 


* The first field states whether the field is initialized in the data 
structure source, and the second field gives the typical access at 
execution time. 
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I.EFN 

I.LN2 ADDRESS OF SECOND LUT WORD 

I.UCB ADDRESS OF REDIRECT UCB 

I.FCN FUNCTION CODE | MODIFIER 

I.IOSB VIRTUAL ADDR OF I/O STATUS BLK 
REAL ADDRESS OF IOSB 

I.AST eocmaea ADDR OF AST SERVICE RTN 

I.PRM 


DEVICE 


PARAMETERS 


Figure 3-1 
I/O Packet Format 
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3.1.1.1 I/O Packet Details - The I/O Packet is built dynamically by 
QIO directive processing. Thus, no static fields exist with respect 


to a driver. I/O Packets are created dynamically and, therefore, the 
first parameter does not apply. Fields in the I/O Packet (described 


below) are classified as: 
Not referenced, 
read-only, or 
read/write. 

I. LNK 
Driver access: 


Not referenced. 


Description: 


Links I/O Packets queued for a driver. A zero ends. the 


chain. The listhead is in the SCB (S.LHD). 


I.PRi 
Driver access: 
Not referenced. 
Description: 
Priority copied from the TCB of the reguesting task. 
I.EFN 
Driver access: 
Not referenced. 


Description: 


Contains the event flag number as copied by QIO directive 


processing from the requester's DPB. 
I.TCB 
Driver access: 
Not referenced. 
Description: 
TCB address of the requesting task. 
I. LN2 
Driver access: 


Not referenced. 


I.UCB 


I. FCN 
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Description: 


Contains the address of the second word of the LUT entry 
the task header to which the I/O request was directed. 


in 


For 


open files on file-structured devices, this word contains the 


address of the Window Block; otherwise, it is zero. 


Driver access: 
Not referenced. 
Description: 


Contains th 
has been s 


Driver access: 
Read-only. 
Description: 


Contains the function code (see Table 3-1) for the 
equest. 


a 


I. IOSB 


Driver access: 
Not referenced. 


Description: 


(IOSB), if one is specified, or zero if not. 


I/O 


IT.IOSB contains the virtual address of the I/O Status’ block 


I.IOSB+2 and I.IOSB+4 contain the address doubleword for the 
IOSB (see Appendix A for a detailed description of the 
address doubleword). On an unmapped system, the first word 


is zero; the second word is the real address of the IOSB. 


In a mapped system, the first word contains the relocation 
bias of the IOSB; the bias is, in effect, the 32-word block 


number in which the IOSB- starts. This block number 


is 


derived by viewing available real memory as a collection of 


32-word blocks numbered consecutively, starting with 
Thus, if the IOSB starts at physical location 3210(8), 
block number is 32(8). 


The second word is formatted as follows: 
Bits 0-5 Displacement in block (DIB) 


Bits 6-12 All zeros 
Bits 13-15 6 


0. 
its 


The displacement in block is the offset from the block base. 


In the above example where the IOSB started at 3210(8), 
DIB is equal to 10(8). 


the 


I.AST 


tH 


tg 
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The value 6 in bits 13-15 is constant. It is used to cause 
an address reference through Kernel Page Address Register 6. 
Again, see Appendix A for details. 


The deferral of a discussion of the address doubleword to an 
appendix reflects the fact that a writer of a conventional 
driver has almost no need to concern himself with the 


contents or format of the address doubleword. Its 
construction and  subseguent manipulation are normally 
external to the driver; Subroutines are provided as 
Executive services for programmed I/0 to render the 


Manipulations of I/O transfers transparent to the driver 
itself. 


Driver access: 


Not referenced. 


Description: 


Contains the virtual address of the AST service routine to be 
executed at I/O completion. If no address is specified, the 
field contains zero. 


Driver access: 


Not initialized, read-only. 


Description: 


Device dependent parameters copied from the DPB. 


The QIO Directive Parameter Block (DPB) is constructed as shown in 
Figure 3-2. 
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Lenora 
FUNCT CODE MODIFIER 


RESERVED LUN 


DEVICE 


DEPENDENT 


PARAMETERS 


LJ] 
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The parameters in the DPB have the following interpretation. 
Length (required): 


The length of the DPB, which for the RSX-11M QIO directive, is 
always fixed at twelve words. 


DIC (reguired): 


Directive Identification Code. For the QIO directive, this value 
isal. 


Function Code (required): 
The code of the requested I/O function (0 thru 31.). 
Modifier: 
Device dependent modifier bits. 
Reserved: 
Reserved byte and must not be used. 
LUN (required): 
Logical Unit Number. 
Priority: 


Request priority. Ignored by RSX-11M, but space must 
be allocated for RSX-11D compatibility. 


EFN (optional): 
Event flag number. 
I/O Status Block Address (optional): 


This word contains a pointer to the I/O status block, which is a 
2-word, device-dependent I/O completion data packet formatted as: 


Byte 0 
I/O status byte. 

Byte l 
Augmented data supplied by the driver. 

Bytes 2 and 3 
The contents of these bytes depend on the value of byte 0. 
If byte 0O-= 1, then these bytes usually contain the 
processed byte count. If byte 0 does not equal zero, then 
the contents are device dependent. 


AST Address (optional): 


Address of an AST service routine. 


3-8 
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Device Dependent Parameters: 


Up to six parameters specific to the device and I/O function 


to 


be performed. Typically, for data transfer functions, these are: 


Buffer address 
Byte count 
Carriage control type 


Logical block number 


Any optional parameters that are not specified should be filled 


zeros. 


3.1.2 The Device Control Block (DCB) 


The 


DCB describes 


Figure 3-3 is a schematic layout of the DCB. 
static characteristics 


to the controller. 


D.LNK 
D.UCB 
D.NAM 
D.UNIT 


D.UCBL 


All fields must be specified. 


LINK TO NEXT DCB (#=LAST) 


LINK TO FIRST UCB 
GENERIC DEVICE NAME 


HIGHEST UNIT # | LOWEST UNIT # 


LENGTH OF UCB 


CONTROL FCN MSK BITS @-15. 


NO-OP'ED FCN MSK BITS f-15. 


ACP FCN MSK BITS @-15. 


LEGAL FCN MSK BITS 16.-32. 


CONTROL FCN MSK BITS 16.-32. 


NO-OP'ED FCN MSK BITS 16.-32. 


ACP FCN MSK BITS 16.-32. 


Figure 3-3 
Device Control Block 


339 


with 


the 


of a device controller and the units attached 


re earn 


D.LNK (Link to next DCB) * 


Driver access: 


Initialized, not referenced. 


Description: 


Address link to the next DCB. 
the last DCB in the chain. 


into the system DCB's via the 
first DCB. 


D.UCB (Pointer to First UCB) 
Driver access: 
Initialized, not referenced. 
Description: 


Address link 


to the first 
asscciated 


with the DCB. 


D.NAM (ASCII Device Name) 


Driver access: 


Initialized, not referenced. 


Description: 


Generic device name in 


ASCII 
mnemonically referenced. 


D.UNIT (Unit Number Range) 


Driver access: 


Initialized, not referenced. 


Description: 


Unit number range for the device. 


logical units available 


D.UCBL (UCB Length) 
Driver access: 


Initialized, not referenced. 


source code. 


* Parenthesized contents indicate value to be initialized in the 
base 


and, 


by 
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DCB Details ~ The fields in the DCB are described below: 


A zero in this field indicates 
The driver writer links his DCB 


global label SUSRTB on his 


possibly, the only UCB 


All UCB's, for a given DCB, are in 
contiguous memory locations and must all be the same length. 


which device units are 


This range covers’ those 


to the user for device assignment. 
Typically, the lowest number is zero, and the highest is n-l, 


where n is the number of device-units described by the DCB. 


data 
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Description: 


The UCB may have any length to meet the needs of the driver 
for variable storage. However, all UCB‘s for a given DCB 
must have the same length. 


D.DSP (Dispatch Table Pointer) 
Driver access: 
Initialized, not referenced. 
Description: 


Address of the driver dispatch table. 


When é Executive wishes to enter the driver at any of the 
four entry points contained in the driver dispatch table, it 
accesses D.DSP, locates the appropriate address in the table, 
and calls the driver at that address. Thus, null addresses 
are not permitted. If the driver does not process a given 
function, then it simply returns. The driver writer must 
provide a driver dispatch table in the driver source. The 
label on this table is of the form SnnTBL and must be a 
global label. The designation nn is the 2-character generic 
device name for the device. Thus, STTTBL is the global label 
on the driver dispatch table for the generic device name TT. 


This table is an ordered, 4-word table containing the 
following entry points: 


Ad 


e 


Gp 
rey 
r 


I/O Initiator; 
Cancel I/O; 

Device Timeout, and 
Power failure. 


When a driver is entered at one of these entry points, entry 
conditions are as follows: 


At Initiator: 
If UC.QUE=1 


R5 UCB address 
Rl Address of the I/O Packet 


If UC.QUE=0 
R5 = UCB address 


Interrupts are allowed. 


At Cancel I/O: 


R5 = UCB address 

R4 = SCB address 

R3 = Controller index 

Rl = Address of TCB of current task 
RO = Address of active I/O packet 


Device interrupts are locked out. 
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At Device Timeout: 


R5 = UCB address 

R4 = SCB address 

R3 = Controller index 

RO = I/O status code IE.DNR (Device Not Ready) 


Device interrupts are locked out. 


At Power Failure: 


R5 = UCB address 
R4 = SCB address 
R3 = Controller index 


Interrupts are allowed. 
D.MSK (Function Masks) 

Driver access: 
Initialized, not referenced. 

Description: 
There are eight words, beginning at D.MSK, which are of 
Critical importance to the proper functioning of a device 
driver. The Executive uses these words to validate and 


dispatch the I/O request specified by a QIO directive. The 
description which follows applies only to non-file-structured 


devices, since directions for writing drivers for 
file-structured devices (drivers which interface to FCP) are 
not included in this manual. Four masks, 2-words per mask, 


are described by the bit configurations established by the 
driver writer for these words. 


1. Legal function mask; 

2. Control function mask; 

3. No-op'ted function mask, and 
4. ACP function mask. 


The QIO directive allows for 32 possible I/O functions. The 
masks, as stated, are filters to determine validity and I/O 
requirements for the subject driver. 


The function value in the I/O request is filtered by the 
Executive through the four mask words. I/O function codes 
range from 0-31. If the function corresponds to a true 
condition in a mask word, a bit is set in the mask in the 
position which numerically corresponds to the function code. 
Thus, if the function 5 is legal, then bit 5 in the Legal 
Function Mask is set. 


The masks are laid out in memory in two 4-word groups. Each 
4-word group covers 16 function codes. The first four words 
cover the function codes 0-15; the second four words cover 
codes 16-31. Below is the exact layout used for the driver 
example in Chapter 5. 
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- WORD 140033 ;LEGAL FUNCTION MASK CODES 0-15. 

- WORD 30 ; CONTROL FUNCTION MASK CODES 0-15. 

. WORD 140000 ;NO-OP'ED FUNCTION MASK-CODES 0-15. 

» WORD 0 ;ACP FUNCTION MASK CODES 0-15. 

-WORD 5 ; LEGAL FUNCTION MASK CODES 16.-31. 
-WORD 0 ;CONTROL FUNCTION MASK CODES 16.-31. 
- WORD a ;NO-OP'ED FUNCTION MASK CODES 16.~31. 
- WORD 4 ;ACP FUNCTION MASK CODES 16.-31. 


The mask words filter sequentially as follows: 
Legal Function Mask: 


Legal function values have the corresponding bit position in 
this word set to 1. Function codes that are not legal are 
rejected by QIO directive processing by returning IE.IFC in 


hea TJD etatisce KIASe se andrias sem TD nAArsa ws . 
the I/O status block, provided an IOSB address was specified. 


Control Function Mask: 


If any device-dependent data exists in the DPB, and this data 
does not require further checking by the QIO directive 
processor, the function is considered in the class <control 
function>. Such a function allows QIO directive processing 
to copy the DPB device-dependent data directly into the I/0 
Packet. 


No-op'ed Function Mask: 


A no-op function is any function that is considered 
successful as soon as it is issued. If the function is a 
no-op, QIO directive processing immediately marks the request 
successful; no additional filtering occurs. 


ACP Function Mask: 


If a function code is legal, but neither control nor _  no-op, 
then it is either an ACP function or a transfer function. If 
a function code may require intervention of an Ancillary 
Control Processor (ACP), the corresponding bit in the ACP 
function mask must be set. 

In the specific case of read/write virtual functions, the 
corresponding mask bits may be set at the driver writer's 
option. If the corresponding mask bits for a read/write 
virtual function are set, QIO directive processing will 
recognize that a file-oriented function is being requested to 
a non-file-structured device and convert the request to a 
read/write logical function. 


This conversion is particularly useful. Consider a 
read/write virtual function to a specific device: 


1. If the device is file-structured and a file is open 
on the specified LUN, the block number specified is 
converted from a virtual block number in the file to 
a logical block number on the medium, and the request 
is gueued to the driver as a read/write logical 
function. 


2. If the device is file-structured and no file is open 
on the specified LUN, then an error is returned and 
no further action is taken. 
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3. If the device is not file~structured, then the 
reguest is simply transformed to a read/write logical 
function and queued to the driver. (Specified block 
number is unchanged). 


Transfer Function Processing 


Finally, if the function is not an ACP function, then, by 
default, it is a transfer function. All transfer functions 
cause the QIO directive processor to check the specified 
buffer for legality (i.e., being within the address space of 
the requesting task) and proper alignment (i.e., word or 
byte). Also, the number of bytes being transferred is 
checked for proper modulus (i.e., nonzero and a= proper 
multiple). 


Mask Word Creation 


The creation of the function mask words involves three steps: 


Us 


Ze 


3a. 


3b. 


3c. 


Establish the I/O functions available on the device for which 
driver support is to be provided. 


Check the standard RSX-11M function code values in Table 3-1 


for equivalencies. Only function code 0 is mandatory. 
Function codes 3 and 4, if used, must have the RSX-11M system 
interpretation. It is suggested that functions having an 


RSX-11M system counterpart use the RSX-11M code, but this is 
not required, except in the case where the device is to be 
used in conjunction with an ACP. From the supported function 
list, the two legal function mask words can be built. 


Given the legal function mask, 
The Control Function mask is built by asking: 


Does this function carry a standard buffer address and 
byte count in the first two device-dependent parameter 
words? 


If it does not, then it either gualifies as a control 
function, or the driver itself must effect the checking and 
conversion of any addresses to the format required by the 
driver. (Buffer addresses in standard format are 
automatically converted to Address Doubleword format.) 


Control functions are, essentially, those whose DPB's do not 
contain buffer addresses or counts. 


The No-op Function Mask is created by deciding which legal 
functions are to be no-op'ed. Typically, for File Control 
Services (FCS) compatibility on non-file-structured devices, 
the file access/deaccess functions are selected as legal 
functions, even though no specific action is required to 
access or deaccess a non-file-structured device; thus, the 
accessS/deaccess functions are no-op'‘ed. 


Finally, the ACP functions Write Virtual Block and _ Read 
Virtual Block may be _ included. Other ACP functions that 
might be included fall into the non-conventional driver 
classification and are beyond the scope of this document. 
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3.1.2.2 I/O Function Codes - The filtering process which cascades 
through the function mask words in the DCB uses the function code byte 
supplied in the QIO directive DPB as the match value. Table 3-1 
contains the function code values used for DEC-supplied drivers. 


Table 3-1 
Standard I/O Function Codes 


FUNCTION EQUATED I/O 
VALUE (8) SYMBOLIC FUNCTION 


0 IO. KIL Cancel I/O 
1 IO.WLB Write Logical Block 
2 IO. RLB Read Logical Block 
3 IO.ATT Attach Device 
4 IO.DET Detach Device 
5 Unused 
6 Unused 
| 7 Unused 
| 10 Unused 
| ab | IO.FNA | Find File in Directory 
| 12 Unused 
L3 IO.RNA Remove File from Directory 
| 14 IO. ENA Enter File in Directory 
| 15 IO.ACR Access File for Read 
| 16 IO.ACW Access File for Read/Write 
| 17 | IO.ACE Access File for Read/Write/Extend | 
20 IO.DAC Deaccess File 
21 IO0.RVB Read Virtual Block 
2z IO.WVB Write Virtual Block 
23 IO.EXT Extend File 
24 IO.CRE Create File | 
25 IO.DEL Mark File for Delete 
26 TO.RAT Read File Attributes | 


IO.WAT Write File Attributes 
Unused 
Unused 
Unused 
Unused 
Unused 
Unused 
Unused 


Unused 
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Of the function code values listed in Table 3-1, only I0.KIL is 
mandatory and has ae fixed interpretation. However, if IO.ATT and 
IO.DET are used, they must have the standard .meaning. If QIo 
directive processing encounters a function code of 3 or 4 and the code 
is not no-op'ed, it will assume that they represent Attach device and 


Detach device, respectively. The other codes are suggested but not 
mandatory. The driver writer is free to establish all other function 
code values on non-file~structured devices. The mask words must 


obviously reflect the proper filtering process. 


If a driver is being written for a file-structured device, the 
Standard function codes of Table 3-1 must be used. 


3.1.3 The Status Control Block (SCB) 


Figure 3-4 is a layout of the 1l3-word SCB. The SCB describes’ the 
status of a control unit which can run in parallel with all other 


control units. 


S.LHD DEVICE I/O QUEUE 

LISTHEAD 
S.PRI 
S.VCT VECTOR ADDR/4 DEVICE PRIORITY 
S.CTM 
S.ITM INT TMOUT CNT CURNT TMOUT CNT 
S.CON 
S.STS CTRLR STATUS CONTROLLER #*2 
S.CSR ADDRESS OF CONTROL STATUS REG 
S.PKT ADDRESS OF CURRENT I/O PACKET 
S.FRK FORK LINK WORD 


FORK PC 
FORK R5 
FORK R4 


Figure 3-4 
Status Control Block 
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3.1.3.1 SCB Details - The fields in the SCB are described below: 
S.LHD (first word equals zero; second word points to first) 
Driver access: 
Initialized, not referenced. 
Description: 
Two words which form the I/O queue listhead. The first word 
points to the first I/O Packet in the queue, and the second 
word points to the last I/O Packet in the queue. If the 
queue is empty, the first word is zero, and the second word 
points to the first word. 
S.PRI (device priority) 
Driver access: 
Initialized, not referenced. 
Description: 
Contains the priority at which the device interrupts. 
S.VCT (interrupt vector divided by four) 
Driver access: 
Initialized, not referenced. 
Description: 
Interrupt vector address divided by four. 
S.CTM (initialize to zero) 
Driver access: 
Not initialized, read/write. 
Description: 
RSX-11M supports device timeout, which enables a driver to 
limit the time that elapses between the issuing of an I/O 
Operation and its termination. The current timeout count (in 
seconds) is initialized by moving S.ITM (initial timeout 
count) into S.CTM. The Executive clock service will examine 
active times, decrement them and, if they reach 0, call the 
driver at its device timeout entry point. 
The internal clock count is kept in 1-second increments. 
Thus, a time count of 1 is not precise, since the internal 
Clocking mechanism is operating asynchronously with driver 
execution. The only meaningful minimum clock interval is 2 
if the programmer intends to treat timeout as a_ consistently 
detectable error condition. Note, if the count is 0, thai no 
timeout will occur; it is, in fact, an indication that 
timeout is not operative. The maximum count is 255. The 


driver writer is responsible for setting this field. 
Resetting is at actual timeout or within S$FORK. 
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S.ITM (set to initial timeout count) 
Driver access: 
Initialized, read-only. 
Description: 
Contains the initial timeout value. 
S.CON (controller number times 2) 
Driver access: 
Initialized, read-only. 
Description: 


Controller number multiplied by 2. Used by drivers which are 
written to support more than one controller. S.CON may be 
used by the driver to index into a controller table created 
and maintained internally to the driver itself. Indexing the 
controller table enables the driver to service the correct 


n Aawina intorriuntea 
controller when a device interrupts. 


S.STS (initialize to zero) 
Driver access: 
Initialized, not referenced. 


Description: 


Establishes the controller as busy/not busy. This byte is 
the interlock mechanism for marking a driver as busy for a 


specific controller. Tested and set by SGTPKT and reset by 
SIODON. 


$.CSR (Control Status Register address) 
Driver access: 
Initialized, read/only. 


Description: 


Contains the address of the Control Status Register (CSR) for 
the device controller. S.CSR is used by the driver to 
initiate I/O operations and to access, via indexing, other 
registers related to the device that are located in the I/0 
page. This address need not be a CSR; it need only be a 
member of the device's register set. It is accessed at 
system bootstrap time to determine if the interface exists on 
the system hosting the Executive. The Executive uses this to 
set the off-line bit at bootstrap so system software can be 
interchanged between systems without an intervening system 


generation. Otherwise, it is only accessed by the driver 
itself. 
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S.PKT (Reserve one word of storage) 
Driver access: 
Not initialized, read-only. 
Description: 


Address of the current I/O Packet established by S$GTPKT. 
This field is used to retrieve the I/O Packet address upon 
the completion of an I/O request. 


S.FRK (reserve four words of storage) 


Driver access: 


Description: 


The four words starting at S.FRK are used for fork block 
storage if and when the driver deems it necessary to 
establish itself as a Fork process. Fork block storage 
preserves the state of the driver, which is restored when the 
driver regains control at fork level. This area is 
automatically used if the driver calls S$FORK. 


3.1.4 The Unit Control Block (UCB) 


Figure 3-5 is a layout of the UCB (a variable-length control block). 
One UCB exists for each physical device-unit generated into a system 
configuration. For user-added drivers, this control block is defined 
as part of the source code for the driver data structure. 
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U.DCB 
U.RED 
U.STS 
U.CTL 
U.ST2 
U.UNIT 
U.CWL1 
U.CW2 
U.CW3 
U.CW4 
U.SCB 
U.ATT 
U.BUF 
U.BUE+2 


U.CNT 


CONTROL FLAGS 
STATUS EXT PHYSICAL UNIT # 


CHARACTERISTICS WORD #4 


POINTER TO SCB 


ICB ADDR OF ATTACHED TASK 


BUFFER RELOCATION BIAS 


BUFFER ADDRESS 


BYTE COUNT 


DEVICE 


DEPENDENT 


| STORAGE | 


Figure 3-5 
Unit Control Block 


361.401 
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UCB Details - The fields in the UCB are described below: 


U.DCB (pointer to associated DCB) 


Driver access: 


Initialized, not referenced. 


Description: 


Backpointer to the corresponding DCB. Since the UCB is a key 
control block in the I/O data structure, access to other 
control blocks usually occurs via links implanted in the UCB. 


U- RED (initialized to point to U.DCB of the UCB) 


Driver access: 


Initialized, not referenced. 


Description: 


Contains a pointer to the UCB to which this device unit has 


been redirected. This field is updated as the result of an 


“MCR Redirect command. The redirect chain ends when this word 


points to the UCB itself. 


U.CTL (set by driver writer) 


Driver access: 


Initialized, not referenced. 


Description: 


U.CTL and the function mask words in the DCB drive _ QIO 
directive processing. The driver writer is totally 
responsible for setting up this bit pattern. Any inaccuracy 
in the bit setting of U.CTL will produce erroneous I/O 
processing. Bit symbols and their meaning are as follows: 


UC.ALG - Alignment bit. 


If this bit = 0, then byte alignment of data buffers is 
allowed. If UC.ALG = 1, then buffers must be word 
aligned. 


UC.ATT - Attach/Detach notification. 


If this bit is set, then the driver will be called when 
an Attach/Detach I/O function is processed by S$GTPKT. 
Typically, the driver has no need to obtain control _ for 
Attach/Detach requests, and the Executive performs the 
entire function without any assistance from the driver. 


UC.KIL ~- Unconditional Cancel I/O call bit. 


If set, the driver is to be called on a Cancel I/O 
request, even if the unit specified is not busy. 
Typically, the driver is called on Cancel I/O only if an 
I/O operation is in progress. 
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UC.QUE - Queue bypass bit. 


If set, the QIO directive processor is to cal 


1 the driver 


prior to queueing the I/O Packet. Once gaining 


to-be-gqueued control, the disposition of the 


I/O Packet 


is the driver's responsibility. Typically, an I/O Packet 


is gueued prior to a call to the driver, 
retrieves it by a call to SGTPKT. 


UC.PWF - Unconditional call on power failure bit. 


If set, the driver is always to be called whe 


which later 


n power is 


restored after a power failure occurs. Typically, the 
driver is called on power restoration only when an I/O 


operation is in progress. 
UC.NPR - NPR device bit. 


If set, the device is an NPR device. This bi 


t determines 


the format of the 2-word address in U.BUF (details given 


under the discussion of U.BUF below). 
UC.LGH ~ Buffer size mask bits (2-bits). 


These two bits are used to check if the 
specified in an I/O request is a legal buffer 


00 - Any buffer modulus valid 

01 ~- Must have word alignment modulus 

11 ~ Must have double word-alignment modulus 
10 - Combination invalid. 

UC.ALG and UC.LGH are independent settings. 


UC.ATT, UC.KIL, UC.QUE, and UC.PWF will usuall 
especially for conventional drivers. 


Every driver must, however, be concerned with its 
values for UC.ALG, UC.NPR, and UC.LGH. 


The driver writer is totally responsible for the 
these bits, and erroneous values are likely 
unpredictable results. 
U.STS (initialize to zero) 
Driver access: 
Initialized, not referenced. 


Description: 


This byte contains device~independent status 
The bit meanings are as follows: 


US.BSY - If set, device-unit is busy. 


US.MNT - If set, volume is not MOUnted. 


byte count 
modulus. 


y be zero, 


particular 


values in 
to produce 


information. 
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US.FOR - If set, volume is foreign. 
US.MDM - If set, device is marked for dismount. 
The unused bits in U.STS are reserved for system use and 


expansion. US.MDM, US.MNT, and US.FOR apply only to 
MOUntable devices. 


U.UNIT (unit number) 


Driver access: 


Initialized, read-only. 


Description: 


This byte contains the physical unit number Of the 
device-unit. If the controller for the device Supports only 
a single unit, the unit number is always zero. 


U.ST2 (set by driver writer) 


U.CWl 


Driver access: 


Initialized, not referenced. 


Description: 


This byte contains additional device-independent status 
information. The bit meanings are as follows: 


US.OFL - If set, the device is off-line (that is, not in 
the configuration). 


US.RED -~ If set, the device cannot be redirected. 


The remaining bits are reserved for system use and expansion. 


(set by driver writer) 


Driver access: 


Initialized, not referenced. 


Description: 


The first of a 4-word contiguous cluster of device 
characteristics information. U.CWl and U.CW4 are 
device-independent. U.CW2 and U.CW3 are device-dependent. 
The four characteristic words are retrieved from the UCB and 
placed in the requester's buffer on issuance of a GLUNS 
Executive directive (Get LUN Information). It is the 
responsibility of the driver writer to supply the contents of 
these four words in the assembly source code of the driver 
data structure. 
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U.CWl is defined as follows: 


DV.REC 
DV.CCE 
DV.TTY 
DV.DIR 
DV.SDI 
DV.SQD 
DV.PSE 
DV.COM 


DV.F1l1i 


DV.MNT 


Bit 
Bit 
Bit 
Bit 
Bre 
Bit 
Bit 
Bit 


Bit 


BEE 


U.CW2 (initialize to 


Driver access: 


Initialized, 


Description: 


0--Record-Oriented Device(l=yes) 
l--Carriage-Control Device(l=yes) 
2--Terminal Device(l=yes) 
3--Directory Device(l=yes) 
4--Single Directory Device(l=yes) 
5~-Seaquential Device(l=yes) 
12--Pseudo Device(l=yes) 
13--Device Mountable as a 
Communications Channel (l=yes) 
14--Device mountable as a FILES-11l 
device(1l=Yes) 
15--Device mountable(l=yes) 


zero) 


read/write. 


storage or constants). 


U.CW3 (initialize to zero) 


Driver access: 


Initialized, 


Description: 


storage or constants). 


U.CW4 (set by driver writer) 


Driver access: 


Initialized, 


Description: 


Default buffer size. 


U.SCB (SCB pointer) 


Driver access: 


Initialized, read-only. 


Description: 


Specific to a given device driver (available tor 
read/write. 
Specific to a given device driver (available for 
read-only. 
this 


This field contains a pointer to the SCB for 


general, R4 


table will contain the value in this word, 


working 


working 


UCB. 


In 


on entry to the driver via the driver dispatch 


frequently referenced by service routines. 


Since the 


SCB 


is 


U.ATT 


U.BUF 
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(initialize to zero) 


Driver access: 


Initialized, not referenced. 


Description: 


If a task has attached itself to a device-unit, this field 
contains its TCB address. 


(reserve two words of storage) 


Driver access: 


Not initialized, read/write. 


Description: 


U.BUF labels two consecutive words which serve as a 
communication region between SGTPKT and the driver. If a 
non-transfer function is indicated, then U.BUF, U.BUF+2, and 
U.CNT receive the first three parameter words from the I/O 
Packet. 


For transfer operations, the format of these two words 
depends on the setting of UC.NPR in U.CTL. The driver does 
not format the words; all formatting is completed prior to 
the driver receiving control. For unmapped systems, the 
first word is zero, and the second word is the physical 
address of the buffer. For mapped systems, the format is 
determined by the UC.NPR bit, which is set for an NPR device 
and reset for a program transfer device. 


Format for program transfer devices: 


The format is identical to that for the second two words of 
I.IOSB in the I/O Packet. See section 3.1.1.1. 


In general, the driver will not manipulate these words when 
performing I/O to program transfer device. It most likely 
will use the Executive routines Get Byte, Get Word, Put Byte, 
and Put Word to effect data transfers between the device and 
the user's buffer. 


Format for an NPR device: 


For NPR device drivers, the word layout is as follows: 


Word 1 

Bit 0 Go bit initially set to zero 

Bit. ~1=3 Function code - set to zeros 

Bit.) 8,5 Memory extension bits 

Bit. 6 Interrupt enable-set to zero 

Bits 7-15 Zero 

Word 2 

Bits 0-15 Low-order l6-bits of physical address 
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It is the driver's responsibility to set the function code, 
interrupt enable, and go bits. This must be accomplished by 
a Bit Set (BIS) operation so the extension bitsS are not 
disturbed. The driver is also responsible for moving these 
words into the device control registers to initiate the I/O 
operation. 


Note that when the system iS unmapped, bits 4 and 5 will 
always be zero, but this is transparent to the driver. fThus, 
NPR device drivers will not be cognizant of the mapping state 
in the system. 

The construction of U.BUF, U.BUF+2 and U.CNT occurs only if 
the requested function is a transfer function; if it is not, 
these three words contain the first three words of the I/0O 
Packet. 


The details of the construction of the Address’ Doubleword 
appear in Appendix A. 


U.CNT (reserve one word of storage) 
Driver access: 
Not initialized, read/write. 
Description: 
Contains the byte count of the buffer described by U.BUF. 
The driver will use this field in constructing the actual 
device request. 
U.BUF and U.CNT are used to keep track of the current data 
item in the buffer for the current transfer (except for NPR 
transfers). Since this field is being altered dynamically, 
the I/O Packet may be needed to reissue an I/O operation. 
Device-Dependent Words: 
Driver access: 
Not initialized, read/write. 


Description: 


The field is variable in length and is established by the 
driver writer to suit driver-specific requirements. 


3=26 


CHAPTER 4 


EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 


This section contains the Executive routines typically used by I/0 
drivers. They are listed in alphabetical order. The descriptions are 
taken directly from the code for the associated service. 


4.1 SYSTEM-STATE REGISTER CONVENTIONS 


In system state, R5 and R4 are, by convention, established as 
non-volatile registers. This means that an internally called routine 
is required to save and restore these two registers if it intends to 
destroy their contents. Note that drivers are entered directly from 
interrupts and have to call SINTSV to preserve R5 and R4. 


R3, R2, Rl, and RO are volatile registers and may be used by a called 
routine without save and restore responsibilities. 


A routine may violate these conventions, as long as an explicit 
statement exists in the program preface detailing the departure from 
conventions. Such departures should be avoided and employed only when 


ample justification can be given to demonstrate the value added to 
overall system performance by virtue of the proposed departure. 


4.2 SERVICE CALLS 

DEVICE MESSAGE OUTPUT 
Device Message Output is in the file IOSUB. 

Calling seguence: 


CALL SDVMSG 


EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 


Description: 


**-SDVMSG-DEVICE MESSAGE OUTPUT 


THIS ROUTINE IS CALLED TO SUBMIT A MESSAGE TO THE TASK TERMINATION 
NOTIFICATION TASK. MESSAGES ARE EITHER DEVICE RELATED OR A CHECKPOINT 


; WRITE FAILURE FROM THE LOADER. 
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INPUTS: 


RO=MESSAGE NUMBER. 
R5=ADDRESS OF THE UCB OR TCB THAT THE MESSAGE APPLIES TO. 


OUTPUTS: 


A FOUR WORD PACKET IS ALLOCATED, RO AND R5 ARE STORED IN THE 
SECOND AND THIRD WORDS, RESPECTIVELY, AND THE PACKET IS THREADED 
INTO THE TASK TERMINATION NOTIFICATION TASK MESSAGE QUEUE. 


NOTE: IF THE TASK TERMINATION NOTIFICATION TASK IS NOT INSTALLED 
OR NO STORAGE CAN BE OBTAINED, THEN THE MESSAGE REQUEST 
IS IGNORED. 


Drivers use only two codes in calling SDVMSG: T.NDNR (device 
not ready), and T.NDSE (select error). SDVMSG can be set up 
and called as follows: 

MOV #T.NDNR, RO 


or 


MOV #T.NDSE,RO 
CALL S$DVMSG 


EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 


FORK | SFORK 

Redes ate | 
Fork is in the file SYSXT. SFORK is called by a driver to switch from 
a partially interruptible level (its state following a call on SINTSV) 
to a fully interruptible level. ; 


Calling sequence: 
CALL SFORK 


Description: 


+ 


**-SFORK-FORK AND CREATE SYSTEM PROCESS 


THIS ROUTINE IS CALLED FROM AN I/O DRIVER TO CREATE A SYSTEM PROCESS THAT 
WILL RETURN TO THE DRIVER AT STACK DEPTH ZERO TO FINISH PROCESSING. 


INPUTS: 
R5=ADDRESS OF THE UCB FOR THE UNIT BEING PROCESSED. 
OUTPUTS: 
REGISTERS R5 AND R4 ARE SAVED IN THE CONTROLLER FORK BLOCK AND 


A SYSTEM PROCESS IS CREATED. THE PROCESS IS LINKED TO THE FORK 
QUEUE AND A JUMP TO SINTXT IS EXECUTED. 
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1. SFORK cannot be called unless SINTSV has been previously called. 
fork processing routine assumes that entry conditions are set 
SINTSV. 
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GET BYTE SGTBYT 


Get Byte is in the file BFCTL. 
Calling sequence: 
CALL SGTBYT 


Description: 


+ 


**-SGTBYT~GET NEXT BYTE FROM USER BUFFER 
THIS ROUTINE IS CALLED TO GET THE NEXT BYTE FROM THE USER BUFFER 
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE BYTE HAS BEEN 
FETCHED, THE NEXT BYTE ADDRESS IS INCREMENTED. 
INPUTS: 

R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
OUTPUTS: 


THE NEXT BYTE IS FETCHED FROM THE USER BUFFER AND RETURNED 
TO THE CALLER ON THE STACK. THE NEXT BYTE ADDRESS IS INCREMENTED. 


ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 


GET PACKET SGTPKT 


Get Packet is in the file IOSUB. 


Calling sequence: 


CALL SGTPKT 


Description: 
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+ 


**-SGTPKT-GET I/O PACKET FROM REQUEST QUEUE 


THIS ROUTINE IS CALLED BY DEVICE DRIVERS TO DEQUEUE THE NEXT I/O REQUEST 
PROCESS. IF THE DEVICE CONTROLLER IS BUSY, THEN A CARRY SET INDICATION If 
RETURNED TO THE CALLER. ELSE AN ATTEMPT IS MADE TO DEQUEUE THE NEXT REQUE 
FROM THE CONTROLLER QUEUE. IF NO REQUEST CAN BE DEQUEUED, THEN A CARRY 
SET INDICATION IS RETURNED TO THE CALLER. ELSE THE CONTROLLER IS SET BUS} 
A CARRY CLEAR INDICATION IS RETURNED TO THE CALLER. 


INPUTS: 
R5=ADDRESS OF THE UCB OF THE CONTROLLER TO GET A PACKET FOR. 
OUTPUTS: 


C=1 IF CONTROLLER IS BUSY OR NO REQUEST CAN BE DEQUEUED. 
C=0 IF A REQUEST WAS SUCCESSFULLY DEQUEUED. 
R1=ADDRESS OF THE I/O PACKET. 
R2=PHYSICAL UNIT NUMBER. 
R3=CONTROLLER INDEX. 
R4=ADDRESS OF THE STATUS CONTROL BLOCK. 
R5=ADDRESS OF THE UNIT CONTROL BLOCK. 


NOTE: R4 AND R5 ARE DESTROYED BY THIS ROUTINE. 


EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 


GET WORD SGTWRD 


Get Word is in the file BFCTL. 
Calling seguence: 
Call SGTWRD 


Description: 


+ 


**-SGTWRD-GET NEXT WORD FROM USER BUFFER 
THIS ROUTINE IS CALLED TO GET THE NEXT WORD FROM THE USER BUFFER 
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE WORD HAS BEEN 
FETCHED, THE NEXT WORD ADDRESS IS CALCULATED. 
INPUTS: 

R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
OUTPUTS: 


THE NEXT WORD IS FETCHED FROM THE USER BUFFER AND RETURNED 
TO THE CALLER ON THE STACK. THE NEXT WORD ADDRESS IS CALCULATED. 


ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 
INTERRUPT SAVE 
Interrupt Save is in the file SYSXT. 
Calling sequence: 
CALL SINTSV,PRn 
n has a range of 0-7. 


Description: 


+ 


**-SINTSV-INTERRUPT SAVE 


“eo we te te 


THIS ROUTINE IS CALLED FROM AN INTERRUPT SERVICE ROUTINE WHEN AN 
INTERRUPT IS NOT GOING TO BE IMMEDIATELY DISMISSED. A SWITCH TO 

THE SYSTEM STACK IS EXECUTED IF THE CURRENT STACK DEPTH IS +l. WHEN 
THE INTERRUPT SERVICE ROUTINE FINISHES ITS PROCESSING, IT EITHER FORKS 
OR JUMPS TO SINTXT. 


~e 


INPUTS: 


(SP)=PS WORD PUSHED BY INTERRUPT. 
(SP)=PC WORD PUSHED BY INTERRUPT. 
(SP)=SAVED R5 PUSHED BY 'JSR R5,SINTSV'. 
(R5)=NEW PROCESSOR PRIORITY. 
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4 
2 
0 
0 
OUTPUTS: 


REGISTER R4 IS PUSHED ONTO THE CURRENT STACK AND THE CURRENT 
STACK DEPTH IS DECREMENTED. IF THE RESULT IS ZERO, THEN 
A SWITCH TO THE SYSTEM STACK IS EXECUTED. THE NEW PROCESSOR 
STATUS IS LOADED AND A RETURN TO THE CALLER IS EXECUTED. 
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INTERRUPT EXIT SINTXT 


Interrupt Exit is in the file SYSXT. 
Calling sequence: 
JMP SINTXT 


Description: 


+ 


*¥*-SINTXT~INTERRUPT EXIT 


THIS ROUTINE IS CALLED VIA A JUMP TO EXIT FROM AN INTERRUPT. IF THE 
STACK DEPTH IS NOT EQUAL TO ZERO, THEN REGISTERS R4 AND R5 ARE 
RESTORED AND AN RTI IS EXECUTED. ELSE A CHECK IS MADE TO SEE 

IF THERE ARE ANY ENTRIES IN THE FORK QUEUE. IF NONE, THEN R4 AND 

R5 ARE RESTORED AND AN RTI IS EXECUTED. ELSE REGISTERS R3 THRU 

RO ARE SAVED ON THE CURRENT STACK AND A DIRECTIVE EXIT IS EXECUTED. 


INPUTS: (MAPPED SYSTEM) 
06(SP)=PS WORD PUSHED BY INTERRUPT. 
04(SP)=PC WORD PUSHED BY INTERRUPT. 
02(SP)=SAVED R5. 
00(SP)=SAVED R4. 

INPUTS: (REAL MEMORY SYSTEM) 


NONE. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 


I/O ALTERNATE ENTRY and I/O DONE SIOALT 
SIODON 


Calling sequences: 


CALL SIOALT 
CALL SIODON 


Description: 
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+ 


**-SIOALT-I/O DONE (ALTERNATE ENTRY) 
**-STODON-I/O DONE 


rt Ta T mn fy 
THIS ROUTINE IS CALLED BY DEVICE D 


TO DO FINAL PROCESSING. THE UNIT A 
ENTERED TO FINISH THE PROCESSING. 


NOP AN T/ON VD 
Wh aaa -/ ww an 


Qn 
DLE AND SIOFIN 


rele 
4 


I 


t 
re 
¢ 
t 
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INPUTS: 
RO=FIRST I/O STATUS WORD. 


R1=SECOND I/O STATUS WORD. 
R5=ADDRESS OF THE UNIT CONTROL BLOCK OF THE UNIT BEING COMPLETED. 
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IF ENTRY IS AT SIOALT, THEN R1 IS CLEARED TO SIGNIFY THAT THE 
SECOND STATUS WORD IS ZERO. 
OUTPUTS: 

THE UNIT AND CONTROLLER ARE SET IDLE. 


R3=ADDRESS OF THE CURRENT I/O PACKET. 


EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 


I/O FINISH SIOFIN 


I/O Finish is in the file IOSUB. Drivers rarely call I/O Finish, but 
they should be aware of the fact that this routine is executed when 
SIOALT or SIODON is called. 
Calling seauence: 

CALL SIOFIN 


Description: 


+ 


**-SIOFIN-I/O FINISH 


THIS ROUTINE IS CALLED TO FINISH I/O PROCESSING IN CASES WHERE THE UNIT AND 
CONTROLLER ARE NOT TO BE DECLARED IDLE. 


INPUTS: 


RO=FIRST I/O STATUS WORD. 
R1=SECOND I/O STATUS WORD. 
R3=ADDRESS OF THE I/O REQUEST PACKET. 
R5=ADDRESS OF THE UNIT CONTROL BLOCK. 
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OUTPUTS: 
THE FOLLOWING ACTIONS ARE PERFORMED: 


1-THE FINAL I/O STATUS VALUES ARE STORED IN THE I/O STATUS BLOCK IF 
ONE WAS SPECIFIED. 


2-THE I/O REQUEST COUNT IS DECREMENTED. IF THE RESULTANT COUNT IS 
ZERO, THEN 'TS.RDN' IS CLEARED IN CASE THE TASK WAS 
STOPPED FOR I/O RUNDOWN. 


3-IF 'TS.CKR' IS SET, THEN IT IS CLEARED AND CHECKPOINTING OF THE 
TASK IS INITIATED. ; 


4-IF AN AST SERVICE ROUTINE WAS SPECIFIED, THEN AN AST IS QUEUED 
FOR THE TASK. ELSE THE I/O PACKET IS DEALLOCATED. 


5-A SIGNIFICANT EVENT OR EQUIVALENT IS DECLARED. 


NOTE: R4 IS DESTROYED BY THIS ROUTINE. 
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PUT BYTE 
Put Byte is in the file BFCTL. 
Calling sequence: 
CALL S$PTBYT 
Description: 


+ 
**-SPTBYT-PUT NEXT BYTE IN USER BUFFER 


=e te 


THIS ROUTINE IS CALLED TO PUT A BYTE IN THE NEXT LOCATION IN 

USER BUFFER. AFTER THE BYTE HAS BEEN STORED, THE NEXT BYTE ADDRESS 
IS INCREMENTED. 

INPUTS: 


R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
2(SP)=BYTE TO BE STORED IN THE NEXT LOCATION OF THE USER BUFFER. 


OUTPUTS: 


THE BYTE IS STORED IN THE USER BUFFER AND REMOVED FROM 
THE STACK. THE NEXT BYTE ADDRESS IS INCREMENTED. 


ALL REGISTERS ARE PRESERVED ACROSS CALL. 


~e “eo SNe “8 “Se ws “SO we we “8S Ne TS BH) NO NO TO NS 


EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 


PUT WORD SPTWRD 


Put Word is in the file BFCTL. 
Calling sequence: 
CALL SPTWRD 


Description: 


+ 


**-SPTWRD-PUT NEXT WORD IN USER BUFFER 

THIS ROUTINE IS CALLED TO PUT A WORD IN THE NEXT LOCATION IN 

USER BUFFER. AFTER THE WORD HAS BEEN STORED, THE NEXT WORD ADDRESS 
IS CALCULATED. 

INPUTS: 


R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
2(SP)=WORD TO BE STORED IN THE NEXT LOCATION OF THE BUFFER. 


OUTPUTS: 


THE WORD IS STORED IN THE USER BUFFER AND REMOVED FROM 
THE STACK. THE NEXT WORD ADDRESS IS CALCULATED. 


ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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CHAPTER 5 


INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE 


The example which follows is a complete illustration of the procedures 
reguired to add a driver to an RSX-11M system. The driver in the 
example supports the punch capability of the PCll Paper Tape 
Reader/Punch. 


5.1 DEVICE DESCRIPTION 


The PCll Paper Tape Reader/Punch is capable of reading 8-hole, 
unoiled, perforated paper tape at 300 characters-per-second, and 
punching tape at 50 characters-per~-second. The system consists of a 
Paper Tape Reader/Punch and Controller. A unit containing a reader 
only (PR11) is also available. 


In reading tape, a set of photodiodes translates the presence or 
absence of holes in the tape to logic levels representing 1's and O's. 
In punching tape, a mechanism translates logic levels representing 1's 
and O's to the presence or absence of holes in the tape. Any 
infurmation read or punched is parallel-transferred through the 


Controller. When an address is placed on the UNIBUS, the Controller 
decodes the address and determines if the reader or punch has_ been 
selected. If one of the four device register addresses has been 


selected, the Controller determines whether an input or an output 
operation should be performed. An input operation from the reader is 
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cere? : 
initiated when the processor transmits a command to the Paper Tape 
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Reader status register. An output operation is initiated when the 
processor transfers a byte to the Paper Tape Punch buffer register. 


The Controller enables the PDP-1ll System to control the reading or 
punching of paper tape in a flexible manner. The reader can be 
operated independently of the punch; either device can be under 
direct program control or can operate without direct supervision, 
through the use of interrupts, to maintain continuous operation. 


INCLUDING A USER~-WRITTEN DRIVER - AN EXAMPLE 
5.2 DATA STRUCTURE AND DRIVER SOURCE 


The simplicity of writing a conventional driver for RSX-11M is 
obscured by the volume of explanation required to cover the universal 
case. As will be seen below, in a particular case, building a 
conventional driver is indeed a Straightforward and modest 
undertaking. 


5.2.1 The Data Structure 


The data structure source is shown below and is’ self-explanatory. 
Special note should be taken of the legal function mask words, 
Starting at line 45. The standard function codes listed in Table 3-1 
were used in creating the mask. Thus, the Punch driver will accept 
the following I/O functions: 


Cancel I/O 

Write Logical Block 

Attach Device 

Detach Device 

Access File For Read/Write 

Access File For Read/Write/Extend 
Deaccess File 

Write Virtual Block 


Cancel I/O is Mandatory. Write Logical Block is the only transfer 
function actually supported. 


Attach/Detach are control functions. The two Access/Deaccess 
functions are legal for FCS compatibility, but are no-op'ed. Write 
Virtual Block is legal but will be converted to Write Logical Block by 
QIO directive processing. 


The Bit Mask for each function is as follows: 


FUNCTION FUNCTION CODE (OCTAL) MASK(OCTAL) BIT RANGE (DECIMAL) 


CAN 0 000001 O= 15:6 
WLB 1 000002 0-15. 
ATT 3 000010 O=15.. 
DET 4 000020 0-15. 
ACW 16 040000 U=15. 
ACE 17 100000 U=13< 
DEA 20 000001 Leees ls 
WVB 22 000004 lo se3ds 


The legal masks result from adding the 0-15(10) bit-range words to 
form a mask and all the 16(10)-31(10) bit-range words to form the 
second mask. 


The Control, No-op, and ACP masks are created in an analogous fashion, 
matching bit positions with legal function code meanings. 
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The complete mask words appear on lines 45 thru 52 in the data 
structure source. 


The function code selections for record-oriented devices are intended 
to match FCS reauirements for file-structured devices. When FCS 
executes an Access For Write, it will simply be marked a no-op. This 
tends to minimize FCS device-dependent logic. 


Note also on line 84 that the controller number, which is encoded in 
the low byte of the interrupt vector PS word in RSX-11M, is set to 
zero. 


1 .- TITLE USRTB 
2 - IDENT /01/ 
3 
4; 
5 3; COPYRIGHT 1975, DIGITAL EQUIPMENT CORP., MAYNARD, MASS. 
o.% 
7 ; THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A LICENSE FOR USE 
8 ; ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH INCLUSION 
9 ; OF DEC'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH SYSTEM, EXCEPT 
10 ; AS MAY OTHERWISE BE PROVIDED IN WRITING BY DEC. 
ll; 
12 ; THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
13 ; NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
14 ; EQUIPMENT CORPORATION. 
Lo & 
16 ; DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY 
17 ; OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 
18 ;: 
19 ; VERSION Ol 
20 ; 
21 : J. PASCUSNIK 25-NOV-74 
22 ; 
23 : CONTROL BLOCKS FOR PAPER TAPE PUNCH DRIVER 
24 ; 
25 ; MACRO LIBRARY CALLS 
26 3 
27 
28 .MCALL DEVDFS$,HWDDFS 
29 DEVDFS *DEPINE DEVICE CONTROL BLOCK OFFSETS* 
30 HWDDFS ;DEFINE HARDWARE REGISTERS 
31 
32 : 
33 ; PAPER TAPE PUNCH DEVICE DATA BASE 
34 ; 
35 ; PAPER TAPE PUNCH DEVICE CONTROL BLOCK 
36 3 
37 SUSRTB:: 
38 PPDCB: . WORD 0 ;LINK TO NEXT DCB 
39 - WORD - PPO sPOINTER TO FIRST UCB 
40 -ASCII /PP/ sDEVICE NAME 
41 - BYTE 0,0 ;LOWEST AND HIGHEST UNIT NUMBERS COVE 
42 H BY THIS DCB 
43 -WORD PPND-PPST ss LENGTH OF EACH UCB IN BYTES 
44 -WORD SPPTBL *POINTER TO DRIVER DISPATCH TABLE 
45 -WORD 140033 ;LEGAL FUNCTION MASK CODES 0-15. 


* Appendix B lists all macros which exist in RSX-11M and generate control 


offsets. 
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-WORD 30 ;CONTROL FUNCTION MASK CODES 0-15. 
-WORD 140000 ;NO-P'ED FUNCTION MASK CODES 0-15. 
-WORD 0 ;ACP FUNCTION MASK CODES 0-15. 

-WORD 5 ;LEGAL FUNCTION MASK CODES 16.-31. 

- WORD 0 ;CONTROL FUNCTION MASK CODES 16.-31. 
-WORD 1 ;NO-OP'ED FUNCTION MASK CODES 16.-31. 
-WORD 4 ;ACP FUNCTION MASK CODES 16.-31. 


PAPER TAPE PUNCH UNIT CONTROL BLOCK 
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-PPO:: 
PPST=. 
»WORD PPDCB s;BACK POINTER TO DCB 
-WORD 72 POINTER TO REDIRECT UNIT UCB 
- BYTE UC.ATT,0O ; CONTROL PROCESSING FLAG (PASS CONTROL 
4 ON ATTACH/DETACH), UNIT STATUS 
- BYTE 0,0 s;PHYSICAL UNIT NUMBER, UNIT STATUS EXTENSION 
«WORD DV.REC s;FIRST DEVICE CHARACTERISTICS WORD 
. (RECORD-ORIENTED DEVICE) 
»WORD 0 :SECOND DEVICE CHARACTERISTICS WORD 
7 (FOR INTERNAL USE BY DRIVER) 
-WORD 0 sTHIRD DEVICE CHARACTERISTICS WORD 
- (FOR INTERNAL USE BY DRIVER) 
-WORD 64. ;FOURTH DEVICE CHARACTERISTICS WORD 
: (DEFAULT BUFFER SIZE IN BYTES) 
-WORD PPSCB POINTER TO SCB 
-WORD 0 :TCB ADDRESS OF ATTACHED TASK 
- BLKW 1 RELOCATION BIAS OF BUFFER OF CURRENT 
: I/O REQUEST 
- BLKW 1 sADDRESS OF BUFFER OF CURRENT I/O REQUEST 
- BLKW 1 BYTE COUNT OF CURRENT I/O REQUEST 
PPND=. 


PAPER TAPE PUNCH INTERRUPT VECTOR 


me Ne Ne 


-ASECT 
~=74 
-WORD SPPINT ;ADDRESS OF INTERRUPT ROUTINE 
- WORD PR7!0 ;INTERRUPT AT PRIORITY 7 (CONTROLLER=0) 
-PSECT 
; PAPER TAPE PUNCH STATUS CONTROL BLOCK 
PPSCB: -WORD 0 ; CONTROLLER I/O QUEUE LISTHEAD 
; (POINTER TO FIRST ENTRY) 
- WORD go2 7 (POINTER TO LAST ENTRY) 
- BYTE PR4,74/4 ;DEVICE PRI, INTERRUPT VECTOR ADDRESS/4 
.BYTE 0,4 ;CURRENT AND INITIAL TIMEOUT COUNTS 
»- BYTE 0,0 ; CONTROLLER INDEX AND STATUS 
; (O=IDLE, 1=BUSY) 
-WORD 177554 ;ADDRESS OF CONTROL STATUS REGISTER 
- BLKW 1 ;ADDRESS OF CURRENT I/O PACKET 
- BLKW 4 ;FORK BLOCK ALLOCATION 


- END 


INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE 
5.2.2 Driver Code 


The code shown below for the punch capability of the PCll is typical 
for aconventional driver. In fact, many of the descriptive comments 
can be used as a template and easily tailored to a driver for another 
device. A few preliminary comments will simplify the examination of 
the code itself. 


Since the PP driver is a DEC product and will eventually be part of a 
released system, conditionalized sections in the code exist that will 
be included or deleted based on answers provided by the user to. the 
configuration queries posed during system generation. The system 
generation questions determine the value of a symbol defined in the 
assembly prefix file RSXMC.MAC. The conditionalized sections of code 
are then controlled by the value of the symbol. The conditionalized 
code appears in multi-controller drivers and is recommended for all 


: 
driver implementations. 


Conditionalized code for PP is implemented as follows: 


PSSP1l1 is set to the number of controllers the driver is to service. 
This sets the size of CNTBL and conditionally creates 'TEMP', if 
PSSP11 >1. Also, if PSSP11 >1, code is generated to save PS in TEMP 
for retrieval on return from SINTSV, and the controller number is 
decoded from the low-order four bits of the saved PS and used to index 
into CNT8L to obtain the UCB address. For PSS$Pl11=1, CNTBL is one word 
long, TEMP is not necessary, and the UCB address is always the first 
entry in CNTBL. 


The structure of the driver follows the classic RSX-11M form being 
separated into processing code for: 


Initiator; 
Power Failure; 
Interrupt; 


Timeout, and 


The driver itself services only Write Logical, Attach and Detach I/O 
functions. Attach and Detach result in the punching of 170(10) nulls 
each for header and trailer. 


Power Failure and Cancel I/O are handled via device timeout, as is the 
device-not-ready condition. 


The PP driver uses the following Executive services: 


SINTSV 
SINTXT 
SGTPRKT 
SGTBYT 
SDVMSG 


Comments beginning with ';;;' indicate the instruction is being 
executed at a priority level greater than or equal to 4. 


INCLUDING A USER-WRITTEN DRIVER ~ AN EXAMPLE 


The code contained in lines 128-130 is used to inhibit the punching of 
a trailer on ATT/DET if the task is being aborted. This is especially 
desirable when the device is not ready (i.e., out of paper ~ tape) and 
system has generated the detach for the aborting process. 


the 


WOMAN HDO WHF 


TITLE, PPDRV 
- IDENT /01/ 


EQUIPMENT CORPORATION. 


ue “oe we Ne Ne Se oS SA Ne Me Ne NO Ne Fe 


VERSION Ol 


J. PASCUSNIK 25-NOV-74 


PCl1l PAPER TAPE PUNCH DRIVER 


MACRO LIBRARY CALLS 


we SO Me Me Se Be Be Ne Se 


COPYRIGHT 1975, DIGITAL EQUIPMENT CORP., MAYNARD, MASS. 01754 


THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A LICENSE FOR USE 
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH INCLUSION 
OF DEC'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH SYSTEM, EXCEPT 
AS MAY OTHERWISE BE PROVIDED IN WRITING BY DEC. 


THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 


DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY 
OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 


-MCALL ABODFS,DEVDFS,HWDDFS,PKTDFS,TCBDFS$ 


ABODFS 
DEVDFS 
HWDDFS 
PKTDFS 
TCBDFS 


EQUATED SYMBOLS 


en ee ee 


WAIT=100000 
ABORT=40000 
TRAIL=200 
LOCAL DATA 


CONTROLLER IMPURE DATA TABLES 


eo Ne te we NO 


CNTBL: - BLKW PSSP1l 


wLE Gr “PSsPlisl 


TEMP: »BLKW ii 


;DEFINE TASK ABORT CODES 

;DEFINE DEVICE CONTROL BLOCK OFFSETS 
;DEFINE HARDWARE REGISTER SYMBOLS 
;DEFINE I/O PACKET OFFSETS 

;DEFINE TASK CONTROL BLOCK OFFSETS 


PAPER TAPE PUNCH STATUS WORD BIT DEFINITIONS (U.CW2) 


;WAITING FOR DEVICE TO COME ON-LINE (1=YES) 
;ABORT CURRENT I/O REQUEST (1=YES) 
;CURRENTLY PUNCHING TRAILER (1=YES) 


(INDEXED BY CONTROLLER NUMBER) 


;ADDRESS OF UNIT CONTROL BLOCK 


7; TEMPORARY STORAGE FOR CONTROLLER NUMBER 


3-6 


=e =e ‘Oe 


$P 


+ 


Ct ee ee es ee ee? eT er | eT eT 


PP 


me Me Ne M8 Ne MO Me Me Ne te Ne Ne HO NA NO NH MO Me Ne Ne Ne MO Ne NO 


INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE 
Pe ol 


DRIVER DISPATCH TABLE 


PTBL:: .~WORD PPINI ;DEVICE INITIATOR ENTRY POINT 
-WORD PPCAN ;CANCEL I/O OPERATION ENTRY POINT 
-WORD PPOUT ;DEVICE TIMEOUT ENTRY POINT 
- WORD PPPWF _ ;POWERFAIL ENTRY POINT 


**-PPINI-PC11 PAPER TAPE PUNCH CONTROLLER INITIATOR 


THIS ROUTINE IS ENTERED FROM THE QUEUE I/O DIRECTIVE WHEN AN I/O REQUEST 

IS QUEUED AND AT THE END OF A PREVIOUS I/O OPERATION TO PROPAGATE THE EXECU 
TION OF THE DRIVER. IF THE SPECIFIED CONTROLLER IS NOT BUSY, THEN AN ATTEMP 
IS MADE TO DEQUEUE THE NEXT I/O REQUEST. ELSE A RETURN TO THE CALLER IS 
EXECUTED. IF THE DEQUEUE ATTEMPT IS SUCCESSFUL, THEN THE NEXT I/O OPER- 
ATION IS INITIATED. A RETURN TO THE CALLER IS THEN EXECUTED. 


INPUTS: 


R5=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED. 


IF THE SPECIFIED CONTROLLER IS NOT BUSY AND AN I/O REQUEST IS WAIT- 
ING TO BE PROCESSED, THEN THE REQUEST IS DEQUEUED AND THE I/O OPER- 
ATION IS INITIATED. 


-ENABL LSB 
INI: CALL SGTPKT ;GET AN I/O PACKET TO PROCESS 
BCS PPPWF ;IF CS CONTROLLER BUSY OR NO REQUEST 


THE FOLLOWING ARGUMENTS ARE RETURNED BY SGTPRKT: 
RI=ADDRESS OF THE I/O REQUE 
R2=PHYSICAL UNIT NUMBER OF 
R3=CONTROLLER INDEX. 
R4=ADDRESS OF THE STATUS CONTROL BLOCK. 

R5=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED. 


SBu 
THE 


PAPER TAPE PUNCH I/O REQUEST PACKET FORMAT: 


WD. 00 ~- I/O QUEUE THREAD WORD. 

WD. O1 -- REQUEST PRIORITY, EVENT FLAG NUMBER. 

WD. 02 -- ADDRESS OF THE TCB OF THE REQUESTER TASK. 

WD. 03 -- POINTER TO SECOND LUN WORD IN REQUESTER TASK HEADER. 

WD. 04 -- CONTENTS OF THE FIRST LUN WORD IN REQUESTER TASK HEADER (U 
WD. 05 -- I/O FUNCTION CODE (I0O.WLB, IO.ATT OR IO.DET). 

WD. 06 -- VIRTUAL ADDRESS OF I/O STATUS BLOCK. 

WD. 07 -- RELOCATION BIAS OF I/O STATUS BLOCK. 

WD. 10 -- I/O STATUS BLOCK ADDRESS (REAL OR DISPLACEMENT + 140000). 
WD. 11 -- VIRTUAL ADDRESS OF AST SERVICE ROUTINE. 

WD. 12 -- RELOCATION BIAS OF I/O BUFFER. 

WD. 13 -- BUFFER ADDRESS OF I/O TRANSFER. 

WD. 14 -- NUMBER OF BYTES TO BE TRANSFERRED. 


INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE 


118 ; WD. 15 -- NOT USED. 

119 ; WD. 16 ~- NOT USED. 

120 ; WD. 17 -- NOT USED. 

58 WD. 20 -~- NOT USED. 

122 ;: 

P23 

124 MOV R5,CNTBL(R3) sSAVE UCB POINTER FOR INTERRUPT ROUTINE 
125 CLR U.CW2(R5) ;CLEAR ALL SWITCHES 

126 CMPB I.FCN+1(R1),#IO.WLB/256. ;WRITE LOGICAL BLOCK FUNCTION? 
127 BEQ 10$ sIF EO. YES 

128 MOV I.TCB(R1),RO ;GET REQUESTER TCB ADDRESS 

129 BITB #TS.ABO,T.STAT+2 (RO) ;TASK BEING ABORTED? 

130 BNE 65S ;IF NE YES - DON'T PUNCH TRAILER 

ee BES #TRAIL,U.CW2(R5) ;OTHERWISE FUNCTION IS ATTACH OR DETACH 
132 ; SET FLAG TO PUNCH TRAILER 

133 MOV #170.,U.CNT(R5) ;SET COUNT FOR 170 NULLS 

134 10S: BIS #WAIT,U.CW2(R5) ;ASSUME WAIT FOR DEVICE OFF LINE 

135 TST @S.CSR(R4) ;DEVICE OFF LINE? 

136 BMI 80S 7;IF MI YES 

Le. 20S BIC #WAIT,U.CW2(R5) ;DEVICE ON LINE, CLEAR WAIT CONDITION 
138 MOVB S.ITM(R4),S.CTM(R4) ;SET TIMEOUT COUNT 

L393 MOV #100,@S.CSR(R4) ;ENABLE INTERRUPTS 

140 

141 ; 

142 ; POWERFAIL IS HANDLED VIA THE DEVICE TIMEOUT FACILITY AND THEREFORE CAUSES 
143 ; NO IMMEDIATE ACTION ON THE DEVICE. THIS IS DONE TO AVOID A RACE CONDITION 
144 ; THAT COULD EXIST IN RESTARTING THE I/O OPERATION 

145 ; 

146 

147 PPPWF: RETURN : 

148 

149 ;+ 

150 ; **-SPPINT-PC1l1l PAPER TAPE PUNCH CONTROLLER INTERRUPTS 

151 ;- 

152 

153 SPPINT:: 333; REF LABEL 

154 

155 eLET 

156 

157 MOV PS, TEMP 33;SAVE CONTROLLER NUMBER 

158 

159 -LlFTF 

160 

161 CALL SINTSV,PR4 33;SAVE REGISTERS AND SET PRIORITY 
162 

163 eter 

164 

165 MOV TEMP, R4 333; RETRIEVE CONTROLLER NUMBER 

166 BIC #177760,R4 33;CLEAR ALL BUT CONTROLLER NUMBER 
167 ASL R4 37;CONVERT TO CONTROLLER INDEX 

168 MOV CNTBL(R4) ,R5 +33; RETRIEVE ADDRESS OF UCB 

169 

120 . IFF 

171 

172 MOV CNTBL,R5 73; RETRIEVE ADDRESS OF UCB 

173 

174 . ENDC 

175 

176 

177 MOV U.SCB(R5) ,R4 *3;;GET ADDRESS OF STATUS CONTROL BLOCK 
178 MOVB S.ITM(R4),S.CTM(R4) 3;;RESET TIMEOUT COUNT 


he) 


179 
180 
181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
191 
192 
LoS 


194 
195 


dad 


196 
197 
198 
19 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
2aa 
212 
Zs 
214 
215 
216 
217 
218 


91a 


atv 


220 
221 
222 
225 
224 
225 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 


INCLUDING A USER-WRITTEN 


308: 


40S; 
50S: 
60S: 


65S: 
7083 


DEVICE 
MINUTE. 


LY ee) ee eT 


PPOUT: 


80S: 


=e 


CANCEL 


~e te 


PPCAN: 


MOV 
MOV 
BMI 


S.CSR(R4) ,R4 


(R4)+,U.CW3(R5) 


60$ 
#1,U.CNT(R5) 
50s 

U.CW2(R5) 

30$ 

(R4) 

40$ 

SGTBYT 
(SP)+,(R4) 
SINTXT 
U.CNT(R5) 

~ (R4) 

SFORK 
U.SCB(R5) ,R4 
S.PKT(R4),R1 
I.PRM+4(R1),R1 
U.CNT(R5) ,R1 
#I1S.SUC&377,R0 
U.CW3(R5) 

70$ 
#IE.VER&377,R0 
STODON 

PPINI 


DRIVER - AN EXAMPLE 


sPOINT R4 TO CONTROL STATUS REGISTER 
+;SAVE STATUS 

‘IF MI, ERROR 

;DECREMENT CHARACTER COUNT 

s;IF CS, THEN DONE 

sCURRENTLY PUNCHING TRAILER? 
;IF PL NO 

PUNCH A NULL 

BRANCH TO EXIT FROM INTERRUPT 
*GET NEXT BYTE FROM USER BUFFER 
;LOAD BYTE IN OUTPUT REGISTER 
;EXIT FROM INTERRUPT 

s;RESET BYTE COUNT 

;DISABLE PUNCH INTERRUPTS 
*CREATE SYSTEM PROCESS 

OINT R4 TO SCB 

:POINT Rl TO I/O PACKET 

; AND PICK UP CHARACTER COUNT 
*CALCULATE CHARACTERS TRANSFERRED 
s;ASSUME SUCCESSFUL TRANSFER 
*DEVICE ERROR? 

2IF PL NO 

; UNRECOVERABLE HARDWARE ERROR CODE 
s INITIATE I/O COMPLETION 

sBRANCH BACK FOR NEXT REQUEST 


eo =e =e ~e te we YO Ne Ne te WH TE WS OME Ne He Se 


gy HU we se Me we te Ne we we we TO we TH NS te Ne 


TIMEOUT RESULTS IN A NOT READY MESSAGE BEING PUT OUT 4 TIMES A 
TIMEOUTS ARE CAUSED BY POWERFAILURE AND PUNCH FAULT CONDITION 


I/O OPERATION-FORCE I/O 


CMP 
BNE 
BIS 
RETURN 


- END 


@S.CSR(R4) 

PS 
#IE.DNR&377,R0 
U.CW2(R5) ,R1 
70$ 
#IE.ABO&377,R0 
R1 

70$ 


@S.CSR(R4) 
20s 


auy 


#T.NDNR, RO 
#1,S5.CTM(R4) 
S.STS (R4) 
PPPWF 
#15.,S.STS (R4) 
SDVMSG 

LSB 


R1l,1.TCB(RO) 
10$ 
#ABORT,U.CW2(R5) 


;;DISABLE PUNCH INTERRUPT 
3;;ALLOW INTERRUPTS 

ASSUME DEVICE NOT READY ERROR 
;ARE WE WAITING FOR DEVICE READY? 
;IF PL NO, TERMINATE I/O REQUEST 
;ASSUME REQUEST IS TO BE ABORTED 
;ABORT REQUEST? 

7 IF MT YES 

;PUNCH READY? 

SEP PL YES 

;SET FOR NOT READY MESSAGE 

;SET TIMEOUT FOR 1 SECOND 

;TIME TO OUTPUT MESSAGE? 

;IF NE NO 

;SET TO OUTPUT NEXT MESSAGE IN 15. 
;OUTPUT MESSAGE 


. 
e 
® 
f 
e 
‘ 


SEC 


TO COMPLETE IF DEVICE IS NOT READY 


s2sREQUEST FOR CURRENT TASK? 
:3;1F NE NO 
33::SET FOR ABORT IF DEVICE NOT READY 


eee 
ara 


APPENDIX A 


DEVELOPMENT OF THE ADDRESS DOUBLEWORD 


A.1l INTRODUCTION 


RSX-11M can be generated aS a mapped or an unmapped system. Mapped 
systems can accommodate configurations whose maximum physical memory 
is 248k bytes. Individual tasks, however, are limited to 64K bytes. 
The addressing in a mapped system is accomplished by using virtual 
addresses and memory mapping hardware. I/0 transfers, however, use 
physical addresses 18 bits in length. Since the PDP-1ll word size is 
16 bits, some scheme was necessary for internal representation of an 
address until it was actually used in an I/O operation. 


One choice may have been to carry about the hardware virtual address. 
This, however, was rejected since lengthy conversions are involved, 
especially when the user for whom the address was being manipulated 
waS not presently mapped into the memory management registers. 
Additionally, a scheme was needed whereby the mapped/unmapped 
characteristic of a given system would be relatively transparent to 
device drivers. 


The choice was made to encode two words as the internal representation 


of a physical address, and to transform virtual addresses for I/O 
Operations into the internal doubleword format. 


A.2 CREATING THE ADDRESS DOUBLEWORD 


For unmapped systems, the doubleword is simply a word of zeros 
followed by a word containing the real address. 


On receipt of a QIO directive for mapped systems, the buffer address 
in the DPB, which contains a task virtual address, is converted to 
address doubleword format. 


The virtual address in the DPB is structured as follows: 


Bits 0-5 Displacement in 32-word block 
Bits 6-12 Block number 
Bits 13-15 Page Address Register Number (PAR#) 


DEVELOPMENT OF THE ADDRESS DOUBLEWORD 


The internal RSX-11M translation restructures this virtual address 
into an address doubleword as follows: 


The relocation base contained in the PAR specified by the PAR# in the 
virtual address in the DPB is added to the block number in the virtual 
address. This result becomes the first word of the address 
doubleword. It represents the nth 32-word block in a memory viewed as 
a collection of 32-word blocks. Note, that at the time the address 
doubleword is computed, the user issuing the QIO directive is mapped 
into the processor's memory management registers. 


The second word is formed by placing the displacement in block (bits 
0-5 of virtual address) into bits 0-5. The block number field was 
accommodated in the first word and bits 6-12 are cleared. Finally, a 
six is placed in bits 13-15 to enable use of PAR #6, which will be 
used by the Executive to service I/O for program transfer devices. 


For non-program transfer (NPR) devices, the driver reguirements’ for 
manipulating the address doubleword are direct and are discussed with 
the description of U.BUF in section 3.1.4.1. 


APPENDIX B 
SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


eMACRO ABODFS,L,B 
t* 
} TASK ABORT CODES 
NOTE: $,COAD@S,CFLT ARE ALSO SST VECTOR OFFSETS 
$* 
S$,COADs’B%, 9000 ADDRESS AND TRAPS TO 4 
S,CSGFs°R’%o, ySEGMENT FAULT 
S,CcBPT=°R%a, sBREAK PCINT OR TRACE TRAP 
§,CICT=*8°6, sIOT INSTRUCTION 
§,CILI=*8°s, gILLEGAL OR RESERVED INSTRUCTION 


S,CEMTsx"B*du, 
S,CTRPs’B% 32, 
S,CFLT#"A"14, 
§8,CSSTs°A% 16. 
S$ ,CaAST=°8° 14, 
$,CAB9=s°S8%2:, 


yNON RSX EMT INSTRUCTION 

sTRAP INSTRUCTION 

911/740 FLOATING POINT EXCEPTION 
9SST ABOPRT=BAD STACK 

pAST ABORT@=BAD STACK 

pABORT VIA DIRECTIVE 


S,CLRF=°8%22, gTASK LOAD REQUEST FAILURE 
S,CCRFs°8°%2d, $TASK CHECKPOINT READ FAILURE 
S$, TOMG=°8% 26, gTASK EXIT WITH OUTSTANDING 1/0 
S,PRTY=°R’28, #TASK MEMORY PARITY ERROR 


J 
s TASK TERMINATION NOTIFICATION MESSAGE CODES 


T,NONR2°R CR 
Cn Vint 0 
PeMUOEe ce 


TeNCwFs’B°u 


yDEVICE NOT READY 


;DEVICE SELECT ERROR 


= bm be 


sCMECKPOINT WRITE FAILURE 


TNCRES°BR° #CARD READER HARDWARE ERROR 
TINDMOS°R?%R, sDISMOUNT COMPLETE 
TeNLONS°B°% 42, ghINK DOKN (NETWORKS) 
YT NLUPS’A 744, gLINK UP (NETWORKS) 
e“ACk&C ABODFS 
eENDM 
2eENOM 
2“ACPC CLKDFS,L,B 
+ 
CLOCK GUEUE CONTRCL BLOCK OFFSET DEFINITIONS 
CLOCK GUEUE CONTROL BLOCK 
THERE ARE FIVE TYPES CF CLOCK QUEUE CONTROL BLOCKS, EACH CONTROL BLOCK HAS 


~—= 3S SO we BO TS TO =O we Oe 


THE SAME FORMAT IN THE FIRST FIVE WORDS AND DIFFERS IN TRE REMAINING THREE 


THE FOLLOwING CONTROL BLOCK TYPES ARE DEFINEDs 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


 MRKTS ROD 
»SCHD=°B%2 
»SSHT=°2°U 
»SYST2°R "6 
aSYTKER“R, 


pMARK TIME REQUEST 

sTASK REQUEST WITH PERIODIC RESCHEDULING 
ySINGLE SHOT TASK REQUEST 

SINGLE SHOT INTERNAL SYSTEM SUBROUTINE (IDENT) 
SINGLE SHOT INTERNAL SYSTE™ SUBROUTINE (TASK) 


CLOCK QUEUE CONTROL BLOCK TYPE INDEPENDENT OFFSET DEFINTIONS 


eASECT 
EQ 
pL NKS7L? ,BLKK 
eROTs?L*® ,8LKB 
PEPNG*L* 4 SLKS 
arCBe*L*? ,SLK4 
eTIMe Lh? , BLK 


ND es 


gCLOCK GUEUVE THREAD WORD 

gREQUEST TYPE 

sEVENT FLAG NUMBER (MARK TIME CNLY) 

9TC8 ADDRESS OF SYSTE™ SUBROUTINE IDENTIFICATION 
gABSOLUTE TIME WREN REQUEST COMES DUE 


CLOCK QUEUE CONTROL BLOCK=MARK TIME CEPENDENT OFFSET DEFINITIONS 


eC TIMN+4 
psASTE*L?® ,BLKw ¢ 
,SR2CerlL*e ,ALKw 4 


»OSTs*L’ ool Kin 4 


PSTART OF DEPENDENT AREA 
sAST ADDRESS 


aFl A MASK WAEM FRO ents eniipbre 
ar oe eS or a Wwe be 


fina 


pADDRESS OF *BIS*% DESTINATION 


CLOCK GUEUVE CONTROL BLOCKsPERIODIC RESCHEDULING DEPENDENT CFFSET OEFINITIONS 


aC, TIM+4 
@RSIS°L*% ,S5LKH 2 
eUTC2°L* ,SLKKw | 


sSTART OF DEPENGENT ARES 
pRESCHEOULE INTERVAL IN CLOCK TICKS 
PSCHEDULING UIC 


CLOCK GUEUVE CONTROL BLOCK=SINGLE SHOT DEPENDENT CFFSET DEFINITIONS 


aC, TIM+¢ 
eALK& 2 
e BLK 1 


gSTART OF DEPENDENT AREA 
9ThO UNUSED WORDS 
pSCREDULISG UIC 


CLOCK SUEUVE CONTROL BLOCKsSINGLE SHOT INTERNAL SUBROUTINE CFFSET DEFINITIONS 


THERE APE T¥O TYPE CODES FOR THIS TYPE CF REQUESTs°*L? 


TYPE 6SSINGLE SKOT INTERNAL SUBROUTINE waITR & 16 BIT VALUE AS AN IDENTIFIER, 
TYOE BeSINGLE SKOT INTEQNAL SUBROUTINE WITK & TCR ADDRESS AS AN IDENTIFIER, 


eC, TIM+ed 

»SUBE7L? JALK® J 
2 3L Ke 2 

eLGTHS*R?, 
oPSECT 


e*ACRO CLKDFS 
abh nM 
eENDP 


sSTART OF NEPENTENT AREA 

PSUBROUTINE ADDRESS 

yTHO UNUSED »ORDS 

pLENGTH OF CLOCK QUEUE CONTRCL BLOCK 


= *2 es ~wS2 WS 2 WS 8S OS YS HE TS OF TO 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


oMACRO OCBDFS,L,8B 


DEVICE CONTROL BLOCK 


THE DEVICE CONTROL BLOCK (DCB) DEFINES GENERIC INFORMATICN ABOLT A DEVICE 
TYPE AND THE LOWEST AND HIGHEST UNIT NUMBERS, THERE IS AT LEAST ONE DCB 
FOR EACH DEVICE TYPE IN A SYSTEM, FOR EXAMPLE, IF THERE ARE TELETYPES IN A 
SYSTEM, THEN THERE IS AT LEAST ONE DCB WITH THE DEVICE NAME ¢TT?, IF PART 
OF THE TELETYPES WERE INTERFACED VIA OL1ieA°S AND THE FEST VIA A DHI1, THE 
THERE wOULD BE TWO DCB*’S, ONE FOR ALL DLiteaA INTERFACED TELETYPES, AND ONE 
FOR ALL D¥i1 INTERFACED TELETYPES, A SIMILAR SITUATION WOULD ARISE IF A 
SYSTEM CONTAINED TRO RK11 OISK CONTROLLERS, ONE DCB WCULD BE REQUIRED 

FOR EACH CONTROLLER, 


sASECT 
0=2 
DeLNK3’L?® ,8LKw 4 pLINK TO SEXT OCB 
D,UCB:°L’ ,AalLKw } gPOINTER TO FIRFST UNIT CONTROL BLOCK 
D,NAMS°L* ,3LKy 1} sGENERIC DEVICE NAME 
D,UNITs*L° ,RLKB 1 gLOWEST UNIT NUMBER COVERED BY THIS DCB 
2 AL KB 1 pHIGHEST UNIT NUMBER COVERED SY THIS DC8 
D,UCBL:°L*® ,BLK« |} gLENGTH CF EACH UNIT CONTROL BLOCK IN BYTES 
O,DSP3°L* ALK» | sPOINTER TO DRIVER DISPATCH TABLE 
O,MSK3°L* ,SLKW f gLEGAL FUNCTION *ASK CODES 2015, 
eSL Kis { sCONTROL FUNCTION MASK CODES 215, 
o Al <i 1 yNOP°ED FUNCTION MASK CODES 2015, 
BL Ks 1 pACP FUNCTION MASK CODES 2015, 
BL KH i pLEGAL FUNCTION MASK CODES 16,31, 
o BLKE 1 sCONTROL FUNCTION MASK CODES 16,831, 
2GlX* 1 yNOP°ED FUNCTICN MASK CODES 16,231, 
BL Ke 1 yACP FUNCTION MASK CODES 16,831, 
ePSECT 
#* 
y DRIVER DISPATCH TABLE OFFSET DEFINITIONS 
j= 
DO, VINIS*B°? pOEVICE INITIATOR 
D,VCAN=°B°%2 sCANCEL CURRENT I/0 FUNCTION 
D,VOUTS°S°4 pDEVICE TIMEOUT 
D,VPWF2'R% yPOWERFAIL RECOVERY 
»“ACRO OCBDFE,X,Y 
eENDM 
eENOM 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


o“ACRO FULDFS 


} 
» VOLUME CONTROL ALOCK 
’ 


eASECT 
eit 
V,TRCOT: , LK» i 9TRANSACTION COUNT 
VeIFWIs ,SLKY i pINDEX FILE wINDOW 
VeFCRs ALK 2 sFILE CONTROL BLOCK LIST HEAD 
V,IB8LBs ,RLKR 4 pINDEX BIT MAP 1ST LBN HIGH BYTE 
V IBSZ2 RL KA i pINDEX BIT MAP SIZE IN BLOCKS 
ge BLK 1 pINDEX BITMAP 1ST LBN LOW BITS 
VeFMAX$ ,RLK» { yMAX NO, OF FILES ON VOLUME 
VeWISZ: ,BLKA 1 pDFLT SIZE OF “INDO®’ IN NO, OF RTRV PTRS 
gVALUE IS «< 128, 
VeSBCL: ,fLKA i ySTORAGE BIT MAP CLUSTER FACTOR 
V,SBSZ3 , alk | sSTORAGE BIT MAP SIZE IN BLOCKS 
V,SBLSs ,SLKR 1 WSTORAGE BIT MAP {ST LBN HIGH BYTE 
V,FIEX: ,&LKA { sDEFAULT FILE EXTEND SIZE 
gg ALK | sSTORAGE BIT MAP 3ST LBN LOk BITS 
VeVOWN: ,BLK# { sVOLUME CAVER?S UIC 
V,VPROt ,8LK» 4 sVOLUMF PROTECTION 
VeVChAs ,FLK¥ 1 sVOLUME CHARACTERISTICS 
VeFPRO: , ALK { pVOLUME DEFAULT FILE PROTECTION 
VeVFSGs BLK» i yVOLUME FILE SEQUENCE NUMBER 
VeFRBX: ,ALKR yNUMBER OF FREE BLOCKS ON VOLUME HIGH BYTE 
V,LRUC: ,ALXB 1 yCOUNT OF AVAILABLE LRU SLOTS IN FCB LIST 
FL Ke i pNUMBER CF FREE BLOCKS ON VOLUME LOW BITS 
V LGTH?: sSIZE IN PYTES OF VCB 
y FILE CONTSOL BLOCK 
’ 
eASECT 
050 
FeLINK: .8Lks { 9FCB CHAIN POINTER 
F.,FNUM: ,BLKw sFILE NUMBER 
F,FSEQ: ALK i sFILE SEQUENCE NUMBER 
aah Kw { pUNUSED 
F,FOWN?: ,aLKs 4 ;FILE OwNER*S UIC 
FLFPROs ,8lLKx 1 FILE PROTECTION CODE 
FLUCHA: ,BLKR ;USER CONTROLLED CHARACTERISTICS 
F.SCHAS ,BLKB +SYSTEM CONTROLLED CHARACTERISTICS 
F,HDLB: ,BLKe 2 yFILE HEADER LOGICAL BLOCK NUMBER 
sBEGINNIKG OF STATISTICS BLOCK 
F,LBNt ,8LKs 2 pLBN OF VIRTUAL BLOCK 1 IF CONTIGUOUS 


92 IF NON CONTIGUOUS 
F,SIZE: ,SLK 2 sSIZE OF FILE IN BLOCKS 
F,NACS$ ,FLKS i gnG, OF ACCESSES 


FyNLCK: ,8LKS { yNO, OF LOCKS 
S,STRK=,eF,LEN sSIZE CF STATICS BLOCK 
F STAT: ,@LKi | gSTATUS BITS FOR FCR CONSISTING OF 
FO,rACSL 24202 ySET IF FILE ACCESSED FOR KRITE 
FO, DIRSUuaee ySET IF FCS IS IN DIRECTCRY LRU 
FO,CEFSAbAnD sSET IF SIRECTORY EQF NEEDS UPDATING 
FO, FCCsioaea ySET IF TRYING TO FORCE DIRECTORY CONTIG 
F,OREF?: ,&LK» i sOIRECTORY ECF BLOCK NUMBER 
F,ORNM: J BLKe | 91ST “ORD OF AIRECTORY NAME 
Sb Kt 1 sUNUSED 
F,LGTHs ySIZE IN BYTES OF FCR 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


} 
y WINDOW 
j 
eASECT 
02 
wI,RDVEG29 
wI,WRVS1220 
«I, EXT@2eae@ 
wI,LOKsu7ae 
wl, OLKsiaae? 
wT, RPSsieagaae 
WeVBNi ,BLKB { 
WeWISZ: JBLKB { 
oSLKe | 
WeFCBs ,fLKH 1 
WeRTRVi 
ePSECT 
eMACRG FLIDFS 
eEND™ FLLDFS 
eE NON FLLDFS 
e4ACRO HDRDFS,L,B 
3? 


»ASECT 
= 21 
KH, CSP3°L’?.BLKK 
M,HDLNe °L*?.BLKA 
MH, PCBT3:°L*, BLK 
H,PCBC2°L°, BLKY 
eal Ke 
H,OSWE°L?, SLKi 
HPCSe°b* aL Ke 
H FORT: °L°,@LKW 
H,OVLY!°L°, BLKu 
HeEFLMS°L°,BLKW 
H,CUIC3°L*,BLKH 
H,DUIC3°L°,BLKW 
H,IPS3°L*?, BLK 
He IPC3°L?, RLKb 
HeISPs*L%, BL KH 
H,ODVAS°L’, BL Ki 
H,COVL?°L*, BLKw 
Hy TKVAS°L®,BLK& 
He TKVL3?°L* BLKY 
HoPFVAE*L®,SLKW 
Hy FPVAL°L*®, BL Kw 
HRCOVAS°L? BL KW 
gp BL KE 
He FPSAS°L?, BLKH 
SLKe 
H.GARD3°L*, BLKH 
HeNLUNG?L*°, BL KW 
HeLUNS7L?, BL Ke 
ePSECT 


MACRO 
eEND™ 
eENDY 


HORDFS$ 


yLO¥ BYTE = 4 OF MAP ENTRIES ACTIVE 
yHIGH BYTE CONSISTS OF THE FOLLOWING BITS 
pREAD VIRTUAL BLOCK ALLOWED IF SET 
sWRITE VIRTUAL BLOCK ALLOWED IF SET 
sEXTEND ALLOWED IF SET 

ySET IF LOCKED AGAINST SHARED ACCESS 
sSET IF SEACCESS LOCK ENABLED 

yBYPASS ACCESS INTERLOCK IF SET 

sHIGH BYTE OF 1ST VBN MAPPED BY WINDOW 
sSIZE IN RTRV PTRS OF wINDOW (7 BITS) 
pLOW ORDER KORD OF 1ST VBN MAPPED 
yFILE CONTROL BLOCK ADDRESS 


jOFFSET TO 4ST RETRIEVAL POINTER IN WINDOW 


gCURRENT STACK POINTER 
HEADER LENGTH IX BYTES 

yTASK PARTITION DESCRIPTOR 
gCOMMON PARTITION DESCRIPTORS 
gBCUNDRY WORD FOR PCB ADDRESSES (ALWAYS=2) 
gTASK OIRECTIVE STATUS *ORD 

gFCS IMPURE POINTER 

gFORTRAN IMPURE POINTER 

gOVERLAY IMPURE POINTER 

pEVENT FLAG MASK WORDS 

gCURRENT TASK UIC 

gDEFAULT TASK UIC 

gINITIAL PROCESSOR STATUS KORD (PS) 
gINITIAL PROGRAM COUNTER (PC) 

gINITIAL STACK PCINTER (SP) 

,0DT SST VECTOR ADDRESS 

g99T SST VECTOR LENGTH 

sTASK SST VECTOR ADDRESS 

gTASK SST VECTOR LENGTH 

gPQWER FATL AST CONTROL BLOCK ADDRESS 
gFLOATING POINT AST CONTROL BLOCK ADDRESS 
gsRECTEVE AST CONTROL BLOCK ADDRESS 
pRESERVED wORD 

gPOINTER TO FLOATING POINT/EAE SAVE AREA 
gRESERVECD wORD 

sPCINTER TO HEADER GUARD WORD 

gNUMBER OF LUN®’S 

gSTART OF LOGICAL UNIT TABLE 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 
oMACRO HHDDFS,L,B 


j+ 
p HARDWARE REGISTER ADDRESSES AND STATUS CODES 


| ad 

MPCSR3°B°1777U6 pADDRESS CF PDPe1{1/72@ MEMORY PARITY REGISTER 
MPARZ°B°1 72172 pADDRESS OF FIRST MEMORY PARITY REGISTER 
PIRQ=°E°177772 gyPROGRAMMED INTERRUPT REQUEST REGISTER 
PR@S*R*A gPROCESSOR PRIORITY @ 

PR{s°R?us gPROCESSOR PRIORITY 1 

PRUz°3°2%7 gPROCESSCR PRIORITY 4 

PRS2’°8%244 pPROCESSCR PRIORITY 5 

PRos’B°3ra sPROCESSOR PRIORITY 6 

PR73°8°344% gsPROCESSOR PRIORITY 7 

P$s3°B°177776 sPROCESSOR STATUS WORD 

SwRe’B?177572 sCONSOLE SWITCH AND CISPLAY REGISTER 
TPS2°8°477564 psCONSOLE TERMINAL PRINTER STATUS REGISTER 


s+ 
p EXTENDED ARTTHMETIC ELEMENT REGISTERS 


j= 
olF OF ESSEAE 
AC2°B°1773%e sACCUMULATOR 
MOE°B" 177304 psMULTIPLIER@QUOTIENT 
SCs’B°17731% +SHIFT CCUNT 


JENDC 


3+ 
» MEMORY MANAGEMENT HARDH#ARE REGISTERS AND STATUS CODES 


j= 

otf OF MESMGE 
KOSARAS°B° 172362 sKERNEL D PAR @ 
KDSDRGS?R° 172320 gKERNEL D PDR & 
KISARA=%B*172340 KERNEL I PAR G 
KISAR6=°8°172354 PKERNEL I PAR 6 
KISAR7=°8°172356 WKERNEL JT PAR 7 
KISOR22°R°1 723522 sKERNEL I POR @ 
KISD86=°8°172314 yKERNEL I POR 6 
KISDR7=°£°172316 sKERNEL I PAR 7 
SISDRUS*RO17222% ;SUPERVISCR I PNR a 
UDSARAS°E% 177662 sUSER 0 PAR @ 
UDSORAS"R*177b62¢ yUSER 5 PDR eC 
UISARAS°P "477642 tUSER I PAR & 
UISARU=°R°4776S2 ;USER IT PAF a 
UISARS52°8°477652 PUSER I PAR 5 
UISA862°8°477654 yUSES J PAR 6 
UISAR7=5°8°177656 yUSER J PAR 7 
UISERSS’B° 17 76n2 sUSER I POR @ 
UISDRus’8°177els gUSER IT POR & 
UISDR5s°R "177612 gUSER J POR 5 
UISDRGs*R°L77bLu4 1USER J] POR 6 
UISDR7S°E*L77A1LG yUSER I PDR 7 
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UBMPRE* A" LT B2R] pUNIBUS MAPPING REGISTER @ 

CMODES*B*1daegea yCURRENT MODE FIELD OF PS WORD 

PMODES°8°329a2 yPREVIOQUS MOCE FIELD OF PS WORD 

SRO2°B°177572 PSEGMENT STATUS REGISTER @ 

§P32°B°172516 sSEGMENT STATUS REGISTER 3 
eENDC 


3+ 
y FEATURE SYMBOL DEFINITIONS 


$* 
FE,EXTH°R* 4 g11/72@ EXTENDED MEMORY SUPPORT 
FE,MUP=°R%e gyMULTISUSER PROTECTION SUPPORT 
»“ACKO HWODFS 
eENRM 


elIF NDF SSSYOF , LIST 


eMACRO LCBDFS,L,& 
$+ 
y LOGICAL ASSIGNMENT CONTROL BLOCK 


’ 

y TRE LOGICAL ASSIGNMENT CONTROL BLOCK (LCB) IS USED TO ASSOCIATE A 

p LOGICAL MAME wITH A PHYSICAL DEVICE UNIT, LCB°S ARE LINKED TOGETHER 
y TO FORM THE LOGICAL ASSIGNMENTS OF A SYSTEM, ASSIGNMENTS MAY BE ON 


y A SYSTEM AIDE GR LOCAL (TERMINAL) BASIS, 


| ad 

eASECT 
22 
LeLNKS7L® .BLKW | gLINK TO NEXT LCB 
LeNAMe*L? ,BLKw 34 pLOGICAL NAME OF DEVICE 
LeUNITS*L*® ,BLKA 4 pLOGICAL UNIT NUMBER 
LeTYPEs*L® ,BLKB } sTYPE OF ENTRY (OBSYSTEM WIDE) 
LeVCBs°L? ,B8LKW }f TI UCB ADDRESS 
LeASG3°L* ,BLKW { gASSIGNMENT UCB ADDRESS 
LeLGTHE’R? mL LK yLENGTH CF LCB 

gPorect 

.yACEO LCBDFS,X,Y 

eb ND™M 

SEND 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


»MACRO PCBDFS 


j+ 
p PARTITION CONTROL BLOCK OFFSET DEFINITIONS 
j= 


eASECT 
2&2 
PeLNKs ,BLKW 
P,NAM$ ,8LKW 
P,SUBs ,BLKW 
P,MAINS ,@LKW 


pLINK TO NEXT PARTITION PCB 

gPARTITION NAME IN RADSA 

gPOINTER TO NEXT SUBPARTITION 

gPOINTER TO MAIN PARTITION 

P,RELs .8LKr gSTARTING PHYSICAL ADDRESS OCF PARTITION 
P,SIZEs ,ALKe gSIZE OF PARTITICN IN BYTES 

P,BLKS: ySIZE OF PARTITION IN 3QW BLOCKS (SYSTEM ONLY) 
P WAITS ,BLKW gPARTITION WATT QUEVE LISTHEAD (2 WORDS) 
P,SWSZ: , BLK gPARTITION SWAP SIZE (SYSTEM ONLY) 
P,BUSY: ,8LKB gPARTITICN BUSY FLAGS 

P,TCBs ,8LKw yTCB ADDRESS OF QwWNER TASK 

P,NAPR: ,8LKB sNUMBER OF APR*°S TO LOAD 

P STAT! ,BLKE sPARTITION STATUS FLAGS 


— = ps oe FY) 


—- -* ps fw) = 


elF DF MESEMGE 


P.PDRt ,8LKH 4 sCONTENTS OF LAST PDR TO BE LOADED 

P HDR; ,8LKW I POINTER TO HEADER CONTROL BLOCK 
»IFF 

P,HDRSP,REL POINTER TO HEADER CONTROL BLOCK 
ENDC 

P,LGTHa, LENGTH CF PARTITION CONTROL BLOCK 
ePSECT 


i+ 
p PARTITION STATUS BYTE BIT DEFINITIONS 


ye 
PS,COMm222 gLIBRARY OR COMMON BLOCK (18YES) 
PS,PICe1au pPOSITICON INDEPENDENT LIBRARY OR COMMON (4SYES) 
PS,SYSE47 sSYSTEM CONTROLLED PARTITION ({sYES) 
PS,ORVe2e2 yORIVER IS LOADED IN PARTITION (12YES) 
PS,APR&7 pSTARTING APR NUMBER MASK 
aMACRO PCBDFS 
aE NDM 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


eMACRO PKTOFS,L,& 
3+ 
gj ASYNCHRONOUS SYSTEM TRAP CONTROL BLOCK CFFSET DEFINITIONS 
j= 
a 4SECT 
250 
o BLK | gAST QUEUE THREAD wORD 
A,CBLS*L*® .BLRS 1 gLENGTH CF CONTROL SLOCK IN BYTES 
A,BYTS°L? ,3LKw~ 1 yNUMBER CF BYTES TO ALLOCATE ON TASK STACK 
AASTS°L*® , BLK» |} pAST TRAP ADORESS 
ANPR3°L? ,RLAw 1 tNUMBES OF AST PARAMETERS 
A.PRME*L* (ALKu | pFIRST AST PARANETER 
1+ 
9 1/0 PACKET CFFSET DEFINITIONS 
5 
~ASECT 
ea 
TeLNKE°L? ,2LK% | sI1/0 GUEUE THREAD wORD 
TePRit*ki* .SLae 4 sREGLEST PRIGRITY 
Teer NISL 2 eLSe 4 sEVENT FLAG NUMBER 
PefCh er’ Qe les of sTCB ADDRESS OCF RESUESTOR 
TeUN2s?Le ,alKe | sPCINTER TO SECOND LUN wORD 
T,UCB3°L*® ,3LKy | gPOINTER TO UNIT CONTROL BLOCK 
T.PCNg°L* ,BLKA 1 31/0 FUNCTION CODE 
T,1088:°l* ,PLKs sVIRTUAL ADDRESS OF I/0 STATUS BLOC 
fla { 31/0 STATUS BLOCK RELOCATON BIAS 
ofl x 1 31/0 STATUS BLOCK ADDRESS 
PASTS U*: GSK of gAST SERVICE ROUTINE ADDRESS 
IT,PRM!*°L*® .Ab Ke 1 PRESERVED FOR MAPPING PARAMETER #1 
al <» & sPARAMETERS 1 TO 6 
I,LGTHs°F?, gsLENGTH OF I/O REQUEST CONTROL BLOCK 
gPScCr 
e*ACRO PKICFS 
eco" 
oENN 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 
e“YACRG SCBOFS,L,8 


FUS CONTROL BLOCK 


STATUS CONTROL BLOCK (SCB) DEFINES THE STATUS OF & DEVICE CONTROLLER, 
2E Ig CNE SCB3 FOR EACH CONTROLLER IA A SYSTE™, THE SCR IS POINTED 10 
JNIT CONTROL BLOCKS, TO EXPAND ON TRE TELETYPE EXA*PLE aBCVE, EACH TELE= 

INTERFACED VIA A DLdteA WOULD HAVE A SCR SIACE EACH DLited IS AN Ne 
PNDENT INTERFACE UNIT, THE TELETYPES INTERFACED VIA THE D414 “OULD aLso 
1 HAVE AN SCR SINCE THE Dkid Ig A SINGLE CONTROLLER BUT MULTIPLEXES MANY 
rS IN PARALLEL, 


eASECT 
2 


Erie? eS SLKB 4 yNUMBER CF REGISTERS TO COPY OX ERROR 
reek? BLK 4 pOFFSET TC FIRST DEVICE FEVCISTER 
‘s°L* ,PLKw { gSAVED I/O ACTIVE BITMAP AND PCIATER TO EMS 
C2°L? ,BLK» 3 yDEVICE I/O ACTIVE BIT ~asK 
b°L? ,BLKe 2 sCONTROLLER I/C QUEVE LISTHEAD 
Le: ogee Bg pDEVICE PRIORITY 
ye pa Ae 7 PINTERRUPT VECTOR afhRESS su 
rfL* ALKA 4 pCURRENT TIMEOUT COUNT 
ieL* .BLKB f pINITIAL TIMECUT COUNT 
MiL* -3bRe. 4 pCONTRCLLER INDEX 
Leg BLES #CONTROLLER STATUS (72IOLE,1s8USY) 
Le gf eke of pADDRESS OF CONTPCL STATLS REGISTER 
irl 4 Stk w4 gADDRESS OF CURRENT I/C PACKET 
Moe gAbea 4 sFORK/TIME REQUEST BLOCK LINK - ORO 
o ALK» 1 PFORKePC/TIMEMGUEUE FEGUEST TYPE 
oBL Ke 1 pFORK@RS/TIMEMREGUEST IDENTIFICATION 
0 BLK 1 pFORKeRA/TIME SLOW CFDER TIPE 
WL? ,PLKA f gFORKeUNUSEO/TIME@HIGH ORDER TIME/CHANNEL CONTROL BLOCK 
PL Ke i sFORK@UNUSED/TINESSURRCUTINE ANDRESS 
PLS ee Le 6 p1i/7? EXTENDED ME*ORY UNTeuS PEVICE CaalLCck 


sP Sect 


‘US CONTRCL RLOCK PRIORITY BYTE CONDITION COLE STATLS SIT IEFINITIGNS 


gnney yERRCS IK PROGSESS (1SYES) 
ip earn sERRCR LOGGING ENABLED (VsYES) 
SPR OL yERIO® LOGGING AVAILARLE (12¥YES) 
12 SPARE BIT 

,YACEC SCEDFS,X,Y 

SENCM 

eho” 


2*ACRO TCBDFS,L,8 


$+ 


y TASK CONTROL 


’ 
) TASK CONTRCL BLOCK 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


eo ASECT 


ea? 
TeaLNK3°L? 
T,PRIs?L? 
14 L0C4" Lb" 
Te Teh et’ 
TNAM3 °L? 
TAREVL Ss 2E* 
Tekstia’ tL? 
TeEFLGIYL? 
TeUChs"L? 
TeiCsbe’L’ 
TLeST ALL 
Tebent*k* 
T LOVE?L?” 
TePChe" Ll” 
TeMxSZe*l? 
TACT Let 


2bLKH 
eolkB 
eSlKB 
eShKw 
e SL Ki 
eBLKW 2 
sFL Ku 2 
eALKw 2 
eolKw ¢ 
eBLKw { 
eGLKB 3 
eaAkKB 3 
ofl Kw | 
eSlkw 4f 
etl Kw | 
ealKw | 


NG ee 


TeLG&TH=s°8%, 


ToEXT="2%, 
eo” 


i+ 
} TASK STATUS DEFINITIONS 


i 
y TASK STA 
j= 


TS, EXES°R? 


SECT 


TIS wORD 


129429 


TS,OSTS°2* 20028 


TS,MSGEtR° 


12248 


TS, PMDH"°R°UAGS 


TS.§TP=°8? 
TS,REME°R°? 
TS,ACP=°R? 
TS, AST=°R? 
TS,CHK=°8° 


2AAS 
14Aa 
LAr 
222 
{42 


TS,RFXS°R "42 
TS,FXDE°R%2z 


T8,0UTS°8? 
TS,CKP=°R? 
TS,CKR=°9° 
TS,CKI2=°R" 


s+ 
¢ TASK BLOCKING STATUS MASK 


14 
4 
2 
1 


BLOCK 


sUTILITY LINK WORD 

;TASK PRIORITY 

y1/0 PENDING COUNT 

sPOINTER TO T,LNX OF TCB ITSELF 
sTASK NAME IN RADS? 

pRECEIVE QUEUE LISTHEAD 

gAST QUEUE LISTHEAD 

sTASK LOCAL EVENT FLAGS 1932 

sUCB ADDRESS FOR PSEUDO DEVICE *TIe 
sTASK LIST THREAD WORD 

sTASK STATUS WORD AND EXTENSION BYTE 
yLBN GF TASK LOAD IMAGE 

sUCB ADDRESS OF LCAD DEVICE 

yPCB ADDRESS OF TASK PARTITION 
sMAXIMUM SIZE OF TASK IMAGE (MAPPED ONLY) 
sADDRESS OF NEXT TASK IN ACTIVE LIST 
sLENGTH OF TASK CONTROL BLOCK 
sLENGTH OF TCR EXTENSION 


gTASK IS IN EXECUTION (02°8*YES) 

pi/O RUN DOWN IN PROGRESS (12°B* YES) 
sAST RECOGNITION DISABLED (12°B8°YES) 
pABORT MESSAGE BEING OUTPUT (12°B°YES) 
}DUMP TASK ON SYNCHRONOUS ABORT (OsYES) 
;TASK STOPPED FOR TERMINAL INPUT (18YES) 
*REMOVE TASK ON EXIT (18°8°YES) 
pANCILLARY CONTROL PROCESSOR (12°B°YES) 
gAST IN PROGRESS (12°B°YES) 

yTASK IS CHECKPOINTABLE (@m*°B°YES) 
yTASK BEING FIXED IN MEMORY (12°B°YES) 
yTASK FIXED IN MEMORY (1e°B*YES) 

yTASK IS OUT OF MEMORY (12°8°YES) 

gTASK IS CHECKPOINTED (18°B°YES) 
9CHECKPOINT REQUESTED (ia°B*YES) 
yCHECKPOINT DISABLED (is*B8°YES) 


TS, BLXe"R TS CKPITS, CKRITS EXEL TS MSGITS,CUTITS,RONITS,STP 3 


3+ 


y TASK STATUS BYTE EXTENSION 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


S,HLTs°B8%222 ;TASK IS BEING HALTED (1e°R°YES) 
S,PRVS*RI 120 yTASK IS PRIVILEGED (1=°R°YES) 
$,AB02"R* uy sTASK MARKED FOR ABORT (12°8°YES) 
S,MCRa°R%22 sTASK REQUESTED AS EXTERNAL “CR FUNCTION (42°B*YES) 
$,SPNERO 12 $SAVED TS,SPN ON AST IN PROGRESS 
S,SPNa’B eu yTASK SUSPENDED (1s°R°YES) 
S,WFRa’R!D PSAVED TS,WFR ON SST IN PROGRESS 
S,WFRB BOY yTASK IN WAITFOR STATE (12°B*YES) 

MACRO TCBOFS 

eENDM 

eENDM 


o“ACRO UCBDFS,L,8 


UNIT CONTROL BLOCK 


THE UNIT CONTROL BLOCK (UCB) DEFINES THE STATUS OF AN INDIVIOQUAL DEVICE 
UNIT AND TS THE CONTROL BLOCK THAT IS POINTED TO 83Y THE FIRST vORD OF 

AN ASSIGNED LUN, THERE IS ONE UCR FOR EACH DEVICE UNIT OF EACH DCB, THE 
WCBS ASSOCIATED WITH & PARTICULAR DCB ARE CONTIGUOUS IN MEMORY AND ARE 
POINTED TO BY THE DCB, UCB8*°S ARE VARIABLE LENGTH BETWEEN CCB*°S BUT ARE 

OF THE SAME LENGTR FOR A SPECIFIC DCB, TO FINISH THE TELETYPE EXAMPLE ABOVE, 
EACH UNIT ON BOTH INTERFACES WOULD HAVE & UCB, 


eASECT 
=? 
}.DCB8°L* .BLK4 1 3BACK POINTER TO DCB 
I,REOS°L® ,ALKw |} sPOINTER TO REDIRECT UNIT UC 
}CTLE°L*% ,8LKB 4 ;CONTROL PROCESSING FLAGS 
ISTSI°L" ,BLKE 1 sUNIT STATUS 
JUNITS°L® .BLKB 4 sPHYSICAL UNIT NUMSER 
},ST22°L" ,BLKB 4 yUNIT STATUS EXTENSION 
HCWLE°L*? ,BLKK 4 yFIRST DEVICE CHARACTERISTICS WORD 
),Cw22°L* ,BLKW 4 sSECOND DEVICE CHARACTERISTICS wORD 
WCW3R°L* 4BLKW Yt sTHIRD DEVICE CHARACTERISTICS wORD 
WCWUEeL® ,BLKW 4 sFOURTH DEVICE CHARACTERISTICS WORD 
),SCB2°L* ,BLKW t yPOINTER TO SCB 
JATTI°L® ,SLKw ft yTCB ADDRESS OF ATTACHED Task 
),BUFS°L* ,BLKW t PRELCCATION BIAS OF CURRENT I/0 REQUEST 
wBLKK 4 s8UFFER ADDRESS OF CURREXT I/O REQUEST 
JCNTI°L? yBLKw 4 y8YTE COUNT OF CURRENT I/0 REQUEST 


J,ACPS°B°U,CNT+2 gADDRESS OF TCB OF MOUNTED ACP 
J), VOBS*R°U,CNT+4 gADDRESS OF VOLUME CONTROL ALOCK 
},CBF="8°UCMT42 9CONTSOL BUFFER RELOCATION ASD ADDRESS 
J,UICS*B°U ChT+<9,%2> pTERMINAL UIC CTERMINALS ONLY) 

oP SECT 


1+ 
s DEVICE TABLE STATUS DEFINITIONS 


I 
) DEVICE CHARACTERISTICS vORD 1 (U,Cw1) DEVICE TYPE DEFINITION BITS, 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


DV,RECE“S "4 PRECORD ORIENTED DEVICE (1sYES) 
DV,CCL2°8°2 :CARRIAGE CONTROL DEVICE (1eYES) 

OV, TTY=*B*U sTERMINAL DEVICE (1@YES) 

DV, DIRS*A? iz sFILE STRUCTURED DEVICE (1eYES) 
DV,SDI=°B*20 sSINGLE DIRECTORY DEVICE (1mYES) 

OV,SQDE*B 42 ySEQUENTIAL DEVICE (1sYES) 

DV, SWL2°B*4age yUNIT SOFTWARE WRITE LOCKED (1YES) 

DV, PSEe’8* 10000 yPSEUDO DEVICE (18YES) | 

OV, COMS"B* 20000 sDEVICE IS MOUNTABLE AS COM CHANNEL (18YES) 
OV, Fiis’B*4gagg yDEVICE IS MOUNTABLE AS Fil DEVICE (i@YES) 
DV, MNT]*R* i 20¢ar ;DEVICE IS MOUNTABLE (12YES) 


V+ 
y TERMINAL DEPENDENT CHARACTERISTICS wORD 2 (U,CW2) BIT DEFINITIONS 
ge 


U2,DH12°B° 192002 sUNTT IS A DALIZDJ11 CisvES) 

U2,0312°R" 42790 sUNTT ITS A OULL CLSYES) 

U2, RMTE°B* 27002 gUNIT IS REMOTE (12YES) 

U2,L0Gs’B°u22 gUSER LOGGED ON TERMINAL (28YES) 
U2,LwCa*Bb*2aa gLOWER CASE TC UPPER CASE CONVERSION (1sYES 
U2, 0FF="B° 192 pOUTPUT IS TURNED OFF (18YES) 

U2,PNDa°R* aa sOUTPUT BYTE PENDING (18YES) 
U2,AT.=°8%22 gMCR COMMAND AT, BEING PROCESSED (1=YES) 
U2,PRV=S°B°12 sUNTT IS A PRIVILEGED TERMINAL (15YES) 
U2,L382°B°4 gUNIT IS A LA3@S TERMINAL (12YES) 
U@,VT5s°B%2 pUNIT IS A V7GS8 TERMINAL (isYES) 
U2,SLV5°B71 gUNTT IS A SLAVE TERMINAL (18YES) 


i? 
p RH1L*RSA3/RSO4 CHARACTERISTICS WORD 2 (U,CW2) BIT DEFINITIONS 
ad 


U2,RG4m°R° 122289 sUNTT IS A RS@4 (12YES) 

+ 

p RRileTUL6 CHARACTERISTICS wORD 2 (U,CW2) BIT DEFINITIONS 

y= 

U2, 7CH=°B“° 12229 pUNIT IS A 7 CHANNEL DRIVE (1SYES) 


$+ 
» UNIT CONTROL PROCESSING FLAG DEFINITIONS 


ye 

UC, ALGeE°8*°222 g8YTE ALIGNMENT ALLOWED (1=NO0) 

UC, NPR=°28°12¢ yOEVICE IS AN NPR DEVICE (18YES) 

UC GUES°R°4S gCALL ORIVER BEFORE QUEUING (12YES) 

UC, PHFs°R%23 yCALL DRIVER AT POWERFAIL ALWAYS (12YES) 
UC ATT#°R"1u 9CALL DRIVER ON ATTACH/DETACH (12YES) 
UC ,KIL=°B%4 gCALL DRIVER AT I/O KILL ALWAYS (18YES) 
UC, LGH2°A°3 gTRANSFER LENGTH MASK BITS 

1+ 

y UNIT STATUS BIT DEFINTIONS 

j* 


SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


US, 8SY2°8 "222 yUNIT IS BUSY (12YES) 

US ,MNTS°8°1 30 yUNIT IS MOUNTED (@2°B°YES) 

US, FORS*S¢u2 yUNIT IS MOUNTED AS FOREIGN VOLUME (1YES) 
US,MDME°3°22 sUNIT IS MARKED FOR DISMOUNT (1aYES) 


i+ 
y UNIT STATUS EXTENSION BIT DEFINITIONS 


y= 
WS, ,OFL aay pUNTT CPFLINE (42YES) 
US,RPED=*8%2 PUNIT REQIRECTAALE (2=YES) 


+ 
y CARD 2EADER DEPENDENT UNTT STATUS BIT DEFINITIONS 


j= 
US,AB9S°R *4 pUNIT IS MARKED FOR ABORT IF NOT READY (18YES) 
US,“DES°2%2 pUNTT IS IN 229 TRANSLATION NODE (15YES) 


i+ 
y FILES=11 DEPENSCERT UNIT STATUS BITS 
| oad 


US, wCKs"S°4? pWRITE CHECK ENABLED (1SYES) 


t+ 
9 TERMINAL DEPENDENT UNIT STATUS BIT DEFINITIONS 


)= 

US, DS8=2°R712 gUNIT IS DISABLED (1YES) 

US ,CRws?R?u sUNIT IS WAITING FOR CARFIER (12YES) 

US, ECH=*R%e gsUNIT HAS ECHO IN PROGRESS (13YES) 

US, OUT=s°A%4 gUNIT IS EXPECTING QUTPUT INTERRUPT (1eYES) 


j+ 
s LPS11 SEPENCENT UNIT STATUS BIT DEFINITIONS 


| ial 

US,FRK=s"R%2 yFORK IN PROGRESS (18YES) 

US, Shree" pSHAREARLE FUNCTION IN PROGRESS (@2°B°YES) 
o“ACPO UCBDFS,X,Y 
eENtM 
eEND® 
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with software should be reported on a Software 
Problem Repcrt (SPR) form 


Did you find errors in this manual? If so, specify by page. 


Did you find this manual understandable, usable, and well-organized? 
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Is there sufficient documentation on associated system programs 
requirea for use of the software described in this manual? If 
what material is missing and where should it be placed? 
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